CppAD: A C++ Algorithmic Differentiation Package  20171217
for_jac_sparsity.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 for_jac_sparsity$$16 spell 17 Jacobian 18 jac 19 bool 20 const 21 rc 22 cpp 23$$ 24 25$section Forward Mode Jacobian Sparsity Patterns$$26 27 head Syntax$$
28 $icode%f%.for_jac_sparsity( 29 %pattern_in%, %transpose%, %dependency%, %internal_bool%, %pattern_out% 30 )%$$31 32 head Purpose$$ 33 We use$latex F : \B{R}^n \rightarrow \B{R}^m$$to denote the 34 cref/AD function/glossary/AD Function/$$ corresponding to
35 the operation sequence stored in $icode f$$. 36 Fix latex R \in \B{R}^{n \times \ell}$$ and define the function 37$latex $38 J(x) = F^{(1)} ( x ) * R 39$ $$40 Given the cref/sparsity pattern/glossary/Sparsity Pattern/$$ for $latex R$$, 41 code for_jac_sparsity$$ computes a sparsity pattern for$latex J(x)$$. 42 43 head x$$
44 Note that the sparsity pattern $latex J(x)$$corresponds to the 45 operation sequence stored in icode f$$ and does not depend on 46 the argument$icode x$$. 47 (The operation sequence may contain 48 cref CondExp$$ and $cref VecAD$$operations.) 49 50 head SizeVector$$ 51 The type$icode SizeVector$$is a cref SimpleVector$$ class with
52 $cref/elements of type/SimpleVector/Elements of Specified Type/$$53 code size_t$$. 54 55$head f$$56 The object icode f$$ has prototype
57 $codei% 58 ADFun<%Base%> %f% 59 %$$60 The cref ADFun$$ object$icode f$$is not code const$$.
61 After a call to $code for_jac_sparsity$$, a sparsity pattern 62 for each of the variables in the operation sequence 63 is held in icode f$$ for possible later use during 64 reverse Hessian sparsity calculations. 65 66$subhead size_forward_bool$$67 After code for_jac_sparsity$$, if $icode k$$is a code size_t$$ object, 68$codei%
69  %k% = %f%.size_forward_bool()
70 %$$71 sets icode k$$ to the amount of memory (in unsigned character units)
72 used to store the
73 $cref/boolean vector/glossary/Sparsity Pattern/Boolean Vector/$$74 sparsity patterns. 75 If icode internal_bool$$ if false,$icode k$$will be zero. 76 Otherwise it will be non-zero. 77 If you do not need this information for cref RevSparseHes$$
78 calculations, it can be deleted
79 (and the corresponding memory freed) using
80 $codei% 81 %f%.size_forward_bool(0) 82 %$$83 after which icode%f%.size_forward_bool()%$$ will return zero. 84 85$subhead size_forward_set$$86 After code for_jac_sparsity$$, if $icode k$$is a code size_t$$ object, 87$codei%
88  %k% = %f%.size_forward_set()
89 %$$90 sets icode k$$ to the amount of memory (in unsigned character units)
91 used to store the
92 $cref/vector of sets/glossary/Sparsity Pattern/Vector of Sets/$$93 sparsity patterns. 94 If icode internal_bool$$ if true,$icode k$$will be zero. 95 Otherwise it will be non-zero. 96 If you do not need this information for future cref rev_hes_sparsity$$
97 calculations, it can be deleted
98 (and the corresponding memory freed) using
99 $codei% 100 %f%.size_forward_set(0) 101 %$$102 after which icode%f%.size_forward_set()%$$ will return zero. 103 104$head pattern_in$$105 The argument icode pattern_in$$ has prototype
106 $codei% 107 const sparse_rc<%SizeVector%>& %pattern_in% 108 %$$109 see cref sparse_rc$$. 110 If$icode transpose$$it is false (true), 111 icode pattern_in$$ is a sparsity pattern for $latex R$$(latex R^\R{T}$$). 112 113$head transpose$$114 This argument has prototype 115 codei% 116 bool %transpose% 117 %$$
118 See $cref/pattern_in/for_jac_sparsity/pattern_in/$$above and 119 cref/pattern_out/for_jac_sparsity/pattern_out/$$ below. 120 121$head dependency$$122 This argument has prototype 123 codei% 124 bool %dependency% 125 %$$
126 see $cref/pattern_out/for_jac_sparsity/pattern_out/$$below. 127 128 head internal_bool$$ 129 If this is true, calculations are done with sets represented by a vector 130 of boolean values. Otherwise, a vector of sets of integers is used. 131 132$head pattern_out$$133 This argument has prototype 134 codei% 135 sparse_rc<%SizeVector%>& %pattern_out% 136 %$$
137 This input value of $icode pattern_out$$does not matter. 138 If icode transpose$$ it is false (true), 139 upon return$icode pattern_out$$is a sparsity pattern for 140 latex J(x)$$ ($latex J(x)^\R{T}$$). 141 If icode dependency$$ is true,$icode pattern_out$$is a 142 cref/dependency pattern/dependency.cpp/Dependency Pattern/$$
144
145 $head Sparsity for Entire Jacobian$$146 Suppose that 147 latex R$$ is the$latex n \times n$$identity matrix. 148 In this case, icode pattern_out$$ is a sparsity pattern for
149 $latex F^{(1)} ( x )$$( latex F^{(1)} (x)^\R{T}$$ ) 150 if$icode transpose$$is false (true). 151 152 head Example$$
153 $children% 154 example/sparse/for_jac_sparsity.cpp 155 %$$156 The file 157 cref for_jac_sparsity.cpp$$ 158 contains an example and test of this operation. 159 It returns true if it succeeds and false otherwise. 160 161$end
162 -----------------------------------------------------------------------------
163 */
166
168
169 /*!
170 Forward Jacobian sparsity patterns.
171
172 \tparam Base
173 is the base type for this recording.
174
175 \tparam SizeVector
176 is the simple vector with elements of type size_t that is used for
177 row, column index sparsity patterns.
178
179 \param pattern_in
180 is the sparsity pattern for for R or R^T depending on transpose.
181
182 \param transpose
183 Is the input and returned sparsity pattern transposed.
184
185 \param dependency
186 Are the derivatives with respect to left and right of the expression below
187 considered to be non-zero:
188 \code
189  CondExpRel(left, right, if_true, if_false)
190 \endcode
191 This is used by the optimizer to obtain the correct dependency relations.
192
193 \param internal_bool
194 If this is true, calculations are done with sets represented by a vector
195 of boolean values. Othewise, a vector of standard sets is used.
196
197 \param pattern_out
198 The value of transpose is false (true),
199 the return value is a sparsity pattern for J(x) ( J(x)^T ) where
200 \f[
201  J(x) = F^{(1)} (x) * R
202 \f]
203 Here F is the function corresponding to the operation sequence
204 and x is any argument value.
205 */
206 template <class Base>
207 template <class SizeVector>
209  const sparse_rc<SizeVector>& pattern_in ,
210  bool transpose ,
211  bool dependency ,
212  bool internal_bool ,
213  sparse_rc<SizeVector>& pattern_out )
214 { // number or rows, columns, and non-zeros in pattern_in
215  size_t nr_in = pattern_in.nr();
216  size_t nc_in = pattern_in.nc();
217  //
218  size_t n = nr_in;
219  size_t ell = nc_in;
220  if( transpose )
221  std::swap(n, ell);
222  //
224  n == Domain() ,
225  "for_jac_sparsity: number rows in R "
226  "is not equal number of independent variables."
227  );
228  bool zero_empty = true;
229  bool input_empty = true;
230  if( internal_bool )
231  { // allocate memory for bool sparsity calculation
232  // (sparsity pattern is emtpy after a resize)
233  for_jac_sparse_pack_.resize(num_var_tape_, ell);
234  for_jac_sparse_set_.resize(0, 0);
235  //
236  // set sparsity patttern for independent variables
238  zero_empty ,
239  input_empty ,
240  transpose ,
242  for_jac_sparse_pack_ ,
243  pattern_in
244  );
245
246  // compute sparsity for other variables
248  &play_,
249  dependency,
250  n,
251  num_var_tape_,
252  for_jac_sparse_pack_
253  );
254  // set the output pattern
257  );
258  }
259  else
260  {
261  // allocate memory for set sparsity calculation
262  // (sparsity pattern is emtpy after a resize)
263  for_jac_sparse_set_.resize(num_var_tape_, ell);
264  for_jac_sparse_pack_.resize(0, 0);
265  //
266  // set sparsity patttern for independent variables
268  zero_empty ,
269  input_empty ,
270  transpose ,
272  for_jac_sparse_set_ ,
273  pattern_in
274  );
275
276  // compute sparsity for other variables
278  &play_,
279  dependency,
280  n,
281  num_var_tape_,
282  for_jac_sparse_set_
283  );
284  // get the ouput pattern
287  );
288  }
289  return;
290 }
291
292
294 # endif
Check that exp is true, if not print msg and terminate execution.
void get_internal_sparsity(bool transpose, const vector< size_t > &internal_index, const InternalSparsity &internal_pattern, sparse_rc< SizeVector > &pattern_out)
Get sparsity pattern for a sub-set of variables.
void for_jac_sparsity(const sparse_rc< SizeVector > &pattern_in, bool transpose, bool dependency, bool internal_bool, sparse_rc< SizeVector > &pattern_out)
Forward Jacobian sparsity patterns.
size_t nr(void) const
number of rows in matrix
Definition: sparse_rc.hpp:284
sparsity pattern for a matrix with indices of type size_t
Definition: sparse_rc.hpp:212
size_t nc(void) const
number of columns in matrix
Definition: sparse_rc.hpp:287
File used to define the ADFun&lt;Base&gt; class.
void set_internal_sparsity(bool zero_empty, bool input_empty, bool transpose, const vector< size_t > &internal_index, InternalSparsity &internal_pattern, const sparse_rc< SizeVector > &pattern_in)
Update the internal sparsity pattern for a sub-set of rows.
Routines that enable code to be independent of which internal spasity pattern is used.
void for_jac_sweep(const local::player< Base > *play, bool dependency, size_t n, size_t numvar, Vector_set &var_sparsity)
Given the sparsity pattern for the independent variables, ForJacSweep computes the sparsity pattern f...