Debian Codegraph @

include/deal.II/differentiation/ad/ad_drivers.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2018 - 2025 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15 #ifndef dealii_differentiation_ad_ad_drivers_h
16 #define dealii_differentiation_ad_ad_drivers_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/exceptions.h>
21 #include <deal.II/base/types.h>
22
23 #include <deal.II/differentiation/ad/ad_number_traits.h>
24 #include <deal.II/differentiation/ad/ad_number_types.h>
25
26 #include <deal.II/lac/full_matrix.h>
27 #include <deal.II/lac/vector.h>
28
29 #ifdef DEAL_II_WITH_ADOLC
30
31 # include <adolc/adouble.h> // Taped double
32 # include <adolc/adtl.h> // Tapeless double
33 # include <adolc/internal/usrparms.h>
34
35 #endif // DEAL_II_WITH_ADOLC
36
37 #include <limits>
38 #include <vector>
39
40
41 DEAL_II_NAMESPACE_OPEN
42
43
44 namespace Differentiation
45 {
46 namespace AD
47 {
48 /**
49 * @addtogroup Exceptions
50 * @{
51 */
52
53 /**
54 * Exception denoting that a class requires some specialization
55 * in order to be used.
56 */
57 DeclExceptionMsg(
58 ExcRequiresADNumberSpecialization,
59 "This function is called in a class that is expected to be specialized "
60 "for auto-differentiable numbers.");
61
62 /**
63 * Exception denoting that ADOL-C is a required feature.
64 */
65 DeclExceptionMsg(
66 ExcRequiresADOLC,
67 "This function is only available if deal.II is compiled with ADOL-C.");
68
69 /**
70 * This exception is raised whenever the an auto-differentiable number does
71 * not support the required number of derivative operations
72 *
73 * The first parameter to the constructor is the number of derivative
74 * operations that it provides, and the second is the minimum number that
75 * are required. Both parameters are of type <tt>int</tt>.
76 */
77 DeclException2(
78 ExcSupportedDerivativeLevels,
79 std::size_t,
80 std::size_t,
81 << "The number of derivative levels that this auto-differentiable number type supports is "
82 << arg1
83 << ", but to perform the intended operation the number must support at least "
84 << arg2 << " levels.");
85
86 /** @} */
87
88
89 /**
90 * A struct defining a collection of types used within the context of
91 * auto-differentiable numbers.
92 */
93 template <typename ADNumberType, typename T = void>
94 struct Types
95 {
96 /**
97 * Typedef for tape indices.
98 */
99 using tape_index = unsigned int;
100
101 /**
102 * Typedef for tape buffer sizes.
103 */
104 using tape_buffer_sizes = unsigned int;
105 }; // struct Types
106
107
108 /**
109 * A struct defining a collection of special numbers used within the
110 * context of auto-differentiable numbers.
111 */
112 template <typename ADNumberType, typename T = void>
113 struct Numbers
114 {
115 /**
116 * A tape index that is unusable and can be used to invalidate recording
117 * operations.
118 */
119 // Note: We stipulate in the documentation for the helper classes that the
120 // valid tape index range is (invalid_tape_index,max_tape_index).
121 static const typename Types<ADNumberType>::tape_index invalid_tape_index =
122 0u;
123
124 /**
125 * The maximum number of tapes that can be written on one process.
126 */
127 static const typename Types<ADNumberType>::tape_index max_tape_index =
128 std::numeric_limits<typename Types<ADNumberType>::tape_index>::max();
129 }; // struct Numbers
130
131
132 /**
133 * A prototype driver class for taped auto-differentiable numbers.
134 *
135 * It is intended that this class be specialized for the valid
136 * combinations of auto-differentiable numbers and output scalar
137 * number types.
138 *
139 * @tparam ADNumberType A type corresponding to a supported
140 * auto-differentiable number.
141 * @tparam ScalarType A real or complex floating point number type
142 * that is the scalar value type used for input to, and output
143 * from, operations performed with auto-differentiable numbers.
144 * @tparam T An arbitrary type resulting from the application of
145 * the SFINAE idiom to selectively specialize this class.
146 */
147 template <typename ADNumberType, typename ScalarType, typename T = void>
148 struct TapedDrivers
149 {
150 // This dummy class definition safely supports compilation
151 // against tapeless numbers or taped number types that have
152 // not yet been implemented.
153
154 /**
155 * @name Taping
156 * @{
157 */
158
159 /**
160 * Return whether or not this class is tracking calculations performed
161 * with its marked independent variables.
162 */
163 bool
164 is_recording() const;
165
166 /**
167 * Return the tape number which is currently activated for recording or
168 * reading.
169 */
170 typename Types<ADNumberType>::tape_index
171 active_tape_index() const;
172
173 /**
174 * Return whether or not a tape number has already been used
175 * or registered.
176 */
177 bool
178 is_registered_tape(
179 const typename Types<ADNumberType>::tape_index tape_index) const;
180
181 /**
182 * Return whether or not the numerical values of all independent
183 * variables are recorded in the tape buffer.
184 */
185 bool
186 keep_independent_values() const;
187
188 /**
189 * Set the buffer sizes for the next active tape.
190 *
191 * This function must be called before start_recording_operations() for
192 * it to have any influence on the memory allocated to the next recorded
193 * tape.
194 *
195 * @note This function only has an effect when using ADOL-C numbers. As
196 * stated by the ADOL-C manual, it may be desirable to create a file
197 * ".adolcrc" in the program run directory and set the buffer size
198 * therein.
199 * Alternatively, this function can be used to override the settings for
200 * any given tape, or can be used in the event that no ".adolcrc" file
201 * exists.
202 * The default value for each buffer is set at 64 megabytes, a
203 * heuristically chosen value thought to be appropriate for use within
204 * the context of finite element analysis when considering coupled
205 * problems with multiple vector-valued fields discretised by higher
206 * order shape functions, as well as complex constitutive laws.
207 *
208 * @param[in] obufsize ADOL-C operations buffer size
209 * @param[in] lbufsize ADOL-C locations buffer size
210 * @param[in] vbufsize ADOL-C value buffer size
211 * @param[in] tbufsize ADOL-C Taylor buffer size
212 */
213 void
214 set_tape_buffer_sizes(
215 const typename Types<ADNumberType>::tape_buffer_sizes obufsize = 64 *
216 1024 *
217 1024,
218 const typename Types<ADNumberType>::tape_buffer_sizes lbufsize = 64 *
219 1024 *
220 1024,
221 const typename Types<ADNumberType>::tape_buffer_sizes vbufsize = 64 *
222 1024 *
223 1024,
224 const typename Types<ADNumberType>::tape_buffer_sizes tbufsize = 64 *
225 1024 *
226 1024);
227
228 /**
229 * Enable the recording mode for a given tape.
230 *
231 * @param[in] tape_index The index of the tape to be written.
232 * @param[in] keep_independent_values Determines whether the numerical
233 * values of all independent variables are recorded in the
234 * tape buffer.
235 */
236 void
237 start_taping(const typename Types<ADNumberType>::tape_index tape_index,
238 const bool keep_independent_values);
239
240 /**
241 * Disable the recording mode for a given tape.
242 *
243 * @param[in] active_tape_index The index of the (currently active) tape
244 * to be finalized and potentially written to file.
245 * @param[in] write_tapes_to_file A flag that specified whether the tape
246 * should be written to file or kept in memory.
247 */
248 void
249 stop_taping(
250 const typename Types<ADNumberType>::tape_index active_tape_index,
251 const bool write_tapes_to_file);
252
253 /**
254 * Return a list of registered tape indices.
255 */
256 std::vector<typename Types<ADNumberType>::tape_index>
257 get_registered_tape_indices() const;
258
259 /**
260 * Select a tape to record to or read from.
261 *
262 * This function activates a tape, but depending on whether @p read_mode
263 * is set, the tape is either taken as previously written to (and put
264 * into read-only mode), or cleared for (re-)taping.
265 *
266 * @param[in] tape_index The index of the tape to be written to/read
267 * from.
268 *
269 * @note The chosen tape index must be greater than
270 * Numbers<ADNumberType>::invalid_tape_index and less than
271 * Numbers<ADNumberType>::max_tape_index.
272 */
273 void
274 activate_tape(const typename Types<ADNumberType>::tape_index tape_index);
275
276 /**
277 * Return a flag that, when <code>true</code>, indicates that the retaping
278 * of the dependent function for the chosen @p tape_index is necessary for
279 * a reliable computation to be performed.
280 * This may be necessary if a sign comparison within branched operations
281 * yields different results to those computed at the original tape
282 * evaluation point.
283 *
284 * This issue, known as "branch switching", can be clarified by means of
285 * a trivial, contrived example:
286 * @code
287 * ADNumberType func (ADNumberType x, ADNumberType y, ADNumberType z)
288 * {
289 * if (x < y)
290 * return y;
291 * else
292 * return x*z;
293 * }
294 * @endcode
295 * During taping, the conditional statement may be either <tt>true</tt> or
296 * <tt>false</tt>, and the result (with its sensitivities) returned by
297 * this function.
298 * The AD library doesn't just record the parse tree of the operations
299 * applied on the branch chosen at the time to taping, but also checks
300 * that the condition continues to be satisfied. For some other evaluation
301 * of the tape (i.e. for some different inputs @p x and @p y), the other
302 * branch of the conditional check may be chosen. The result of following
303 * this code path has not been recorded on the tape, and therefore cannot
304 * be evaluated. In such a case, the underlying AD library will be able to
305 * tell you that it is necessary to re-record the tape at the new
306 * evaluation point in order to resolve the new code branch. This function
307 * can be used to find out whether this is so.
308 *
309 * @note The chosen tape index must be greater than
310 * Numbers<ADNumberType>::invalid_tape_index and less than
311 * Numbers<ADNumberType>::max_tape_index.
312 */
313 bool
314 requires_retaping(
315 const typename Types<ADNumberType>::tape_index tape_index) const;
316
317 /**
318 * Return a flag that, when <code>true</code>, indicates that the retaping
319 * of the dependent function is necessary for a reliable computation to be
320 * performed on the currently active tape.
321 * This may be necessary if a sign comparison within branched operations
322 * yields different results to those computed at the original tape
323 * evaluation point.
324 *
325 * This issue, known as "branch switching", can be clarified by means of
326 * a trivial, contrived example:
327 * @code
328 * ADNumberType func (ADNumberType x, ADNumberType y, ADNumberType z)
329 * {
330 * if (x < y)
331 * return y;
332 * else
333 * return x*z;
334 * }
335 * @endcode
336 * During taping, the conditional statement may be either <tt>true</tt> or
337 * <tt>false</tt>, and the result (with its sensitivities) returned by
338 * this function.
339 * The AD library doesn't just record the parse tree of the operations
340 * applied on the branch chosen at the time to taping, but also checks
341 * that the condition continues to be satisfied. For some other evaluation
342 * of the tape (i.e. for some different inputs @p x and @p y), the other
343 * branch of the conditional check may be chosen. The result of following
344 * this code path has not been recorded on the tape, and therefore cannot
345 * be evaluated. In such a case, the underlying AD library will be able to
346 * tell you that it is necessary to re-record the tape at the new
347 * evaluation point in order to resolve the new code branch. This function
348 * can be used to find out whether this is so.
349 */
350 bool
351 last_action_requires_retaping() const;
352
353 /**
354 * Completely erases the tape with the given @p tape_index.
355 */
356 void
357 remove_tape(const typename Types<ADNumberType>::tape_index tape_index);
358
359 /**
360 * Reset the state of the class.
361 *
362 * @note This also resets the active tape number to an invalid number, and
363 * deactivates the recording mode for taped variables.
364 */
365 void
366 reset(const bool clear_registered_tapes);
367
368 /**
369 * Print the status of all queryable data. Exactly what is printed and
370 * its format depends on the @p ad_type, as is determined by the
371 * @p ADNumberTypeCode template parameter.
372 *
373 * @param[in] stream The output stream to which the values are to be
374 * written.
375 */
376 void
377 print(std::ostream &stream) const;
378
379 /**
380 * Print the statistics regarding the usage of the tapes.
381 *
382 * @param[in] tape_index The index of the tape to get the statistics of.
383 * @param[out] stream The output stream to which the values are to be
384 * written.
385 */
386 void
387 print_tape_stats(
388 const typename Types<ADNumberType>::tape_index tape_index,
389 std::ostream &stream) const;
390
391 /** @} */
392
393 /**
394 * @name Drivers for scalar functions (one dependent variable)
395 * @{
396 */
397
398 /**
399 * Compute the value of the scalar field.
400 *
401 * @param[in] active_tape_index The index of the tape on which the
402 * dependent function is recorded.
403 * @param[in] independent_variables The scalar values of the independent
404 * variables whose sensitivities were tracked.
405 *
406 * @return The scalar value of the function.
407 */
408 ScalarType
409 value(const typename Types<ADNumberType>::tape_index active_tape_index,
410 const std::vector<ScalarType> &independent_variables) const;
411
412 /**
413 * Compute the gradient of the scalar field with respect to all
414 * independent variables.
415 *
416 * @param[in] active_tape_index The index of the tape on which the
417 * dependent function is recorded.
418 * @param[in] independent_variables The scalar values of the independent
419 * variables whose sensitivities were tracked.
420 * @param[out] gradient The values of the dependent function's
421 * gradients. It is expected that this vector be of the
422 * correct size (with length
423 * <code>n_independent_variables</code>).
424 */
425 void
426 gradient(const typename Types<ADNumberType>::tape_index active_tape_index,
427 const std::vector<ScalarType> &independent_variables,
428 Vector<ScalarType> &gradient) const;
429
430 /**
431 * Compute the Hessian of the scalar field with respect to all
432 * independent variables.
433 *
434 * @param[in] active_tape_index The index of the tape on which the
435 * dependent function is recorded.
436 * @param[in] independent_variables The scalar values of the independent
437 * variables whose sensitivities were tracked.
438 * @param[out] hessian The values of the dependent function's
439 * Hessian. It is expected that this matrix be of the correct
440 * size (with dimensions
441 * <code>n_independent_variables</code>$\times$<code>n_independent_variables</code>).
442 */
443 void
444 hessian(const typename Types<ADNumberType>::tape_index active_tape_index,
445 const std::vector<ScalarType> &independent_variables,
446 FullMatrix<ScalarType> &hessian) const;
447
448 /** @} */
449
450 /**
451 * @name Drivers for vector functions (multiple dependent variables)
452 * @{
453 */
454
455 /**
456 * Compute the values of the vector field.
457 *
458 * @param[in] active_tape_index The index of the tape on which the
459 * dependent function is recorded.
460 * @param[in] n_dependent_variables The number of dependent variables.
461 * @param[in] independent_variables The scalar values of the independent
462 * variables whose sensitivities were tracked.
463 * @param[out] values The component values of the dependent functions.
464 * It is expected that this vector be of the correct size
465 * (with length <code>n_dependent_variables</code>).
466 */
467 void
468 values(const typename Types<ADNumberType>::tape_index active_tape_index,
469 const unsigned int n_dependent_variables,
470 const std::vector<ScalarType> &independent_variables,
471 Vector<ScalarType> &values) const;
472
473 /**
474 * Compute the Jacobian of the vector field.
475 *
476 * The Jacobian of a vector field is in essence the gradient of each
477 * dependent variable with respect to all independent variables.
478 * This operation is therefore analogous to the gradient() operation
479 * performed on a collection of scalar valued fields.
480 *
481 * @param[in] active_tape_index The index of the tape on which the
482 * dependent function is recorded.
483 * @param[in] n_dependent_variables The number of dependent variables.
484 * @param[in] independent_variables The scalar values of the independent
485 * variables whose sensitivities were tracked.
486 * @param[out] jacobian The component values of the dependent functions'
487 * Jacobian. It is expected that this matrix be of the correct
488 * size (with dimensions
489 * <code>n_dependent_variables</code>$\times$<code>n_independent_variables</code>).
490 */
491 void
492 jacobian(const typename Types<ADNumberType>::tape_index active_tape_index,
493 const unsigned int n_dependent_variables,
494 const std::vector<ScalarType> &independent_variables,
495 FullMatrix<ScalarType> &jacobian) const;
496
497 /** @} */
498 };
499
500
501
502 /**
503 * A prototype driver class for tapeless auto-differentiable numbers.
504 *
505 * It is intended that this class be specialized for the valid
506 * combinations of auto-differentiable numbers and output scalar
507 * number types.
508 *
509 * @tparam ADNumberType A type corresponding to a supported
510 * auto-differentiable number.
511 * @tparam ScalarType A real or complex floating point number type
512 * that is the scalar value type used for input to, and output
513 * from, operations performed with auto-differentiable numbers.
514 * @tparam T An arbitrary type resulting from the application of
515 * the SFINAE idiom to selectively specialize this class.
516 */
517 template <typename ADNumberType, typename ScalarType, typename T = void>
518 struct TapelessDrivers
519 {
520 // This dummy class definition safely supports compilation
521 // against taped numbers or tapeless number types that have
522 // not yet been implemented.
523
524 /**
525 * @name Configuration
526 * @{
527 */
528
529 /**
530 * In the event that the tapeless mode requires <i>a priori</i> knowledge
531 * of how many directional derivatives might need to be computed, this
532 * function informs the auto-differention library of what this number
533 * is.
534 *
535 * @param[in] n_independent_variables The number of independent variables
536 * that will be used for the entire duration of the
537 * simulation.
538 *
539 * @warning For ADOL-C tapeless numbers, the value given to
540 * @p n_independent_variables should be the <b>maximum</b> number of
541 * independent variables that will be used for the entire duration of
542 * the simulation. This is important in the context of, for example,
543 * hp-FEM and for multiple constitutive models with a different number of
544 * fields from which a linearization must be computed.
545 */
546 static void
547 initialize_global_environment(const unsigned int n_independent_variables);
548
549 /** @} */
550
551 /**
552 * Operation status
553 * @{
554 */
555
556 /**
557 * Set a flag that states that we can safely mark dependent variables
558 * within the current phase of operations.
559 */
560 void
561 allow_dependent_variable_marking();
562
563 /**
564 * Set a flag that states that we cannot safely mark dependent variables
565 * within the current phase of operations.
566 */
567 void
568 prevent_dependent_variable_marking();
569
570 /**
571 * Query a flag as to whether or not dependent variables can be marked
572 * within the current phase of operations.
573 */
574 bool
575 is_dependent_variable_marking_allowed() const;
576
577 /** @} */
578
579 /**
580 * @name Drivers for scalar functions
581 * @{
582 */
583
584 /**
585 * Compute the value of the scalar field.
586 *
587 * @param[in] dependent_variables The dependent variables whose values are
588 * to be extracted.
589 *
590 * @return The scalar value of the function.
591 */
592 ScalarType
593 value(const std::vector<ADNumberType> &dependent_variables) const;
594
595 /**
596 * Compute the gradient of the scalar field with respect to all
597 * independent variables.
598 *
599 * @param[in] independent_variables The independent variables whose
600 * sensitivities were tracked.
601 * @param[in] dependent_variables The (single) dependent variable whose
602 * gradients are to be extracted.
603 * @param[out] gradient The values of the dependent function's
604 * gradients. It is expected that this vector be of the
605 * correct size (with length
606 * <code>n_independent_variables</code>).
607 */
608 void
609 gradient(const std::vector<ADNumberType> &independent_variables,
610 const std::vector<ADNumberType> &dependent_variables,
611 Vector<ScalarType> &gradient) const;
612
613 /**
614 * Compute the Hessian of the scalar field with respect to all
615 * independent variables.
616 *
617 * @param[in] independent_variables The independent variables whose
618 * sensitivities were tracked.
619 * @param[in] dependent_variables The (single) dependent variable whose
620 * Hessians are to be extracted.
621 * @param[out] hessian The values of the dependent function's
622 * Hessian. It is expected that this matrix be of the correct
623 * size (with dimensions
624 * <code>n_independent_variables</code>$\times$<code>n_independent_variables</code>).
625 */
626 void
627 hessian(const std::vector<ADNumberType> &independent_variables,
628 const std::vector<ADNumberType> &dependent_variables,
629 FullMatrix<ScalarType> &hessian) const;
630
631 /** @} */
632
633 /**
634 * @name Drivers for vector functions
635 * @{
636 */
637
638 /**
639 * Compute the values of the vector field.
640 *
641 * @param[in] dependent_variables The dependent variables whose Hessians
642 * are to be extracted.
643 * @param[out] values The component values of the dependent functions.
644 * It is expected that this vector be of the correct size
645 * (with length <code>n_dependent_variables</code>).
646 */
647 void
648 values(const std::vector<ADNumberType> &dependent_variables,
649 Vector<ScalarType> &values) const;
650
651 /**
652 * Compute the Jacobian of the vector field.
653 *
654 * The Jacobian of a vector field is in essence the gradient of each
655 * dependent variable with respect to all independent variables.
656 * This operation is therefore analogous to the gradient() operation
657 * performed on a collection of scalar valued fields.
658 *
659 * @param[in] independent_variables The independent variables whose
660 * sensitivities were tracked.
661 * @param[in] dependent_variables The dependent variables whose Jacobian
662 * are to be extracted.
663 * @param[out] jacobian The component values of the dependent functions'
664 * Jacobian. It is expected that this matrix be of the correct
665 * size (with dimensions
666 * <code>n_dependent_variables</code>$\times$<code>n_independent_variables</code>).
667 */
668 void
669 jacobian(const std::vector<ADNumberType> &independent_variables,
670 const std::vector<ADNumberType> &dependent_variables,
671 FullMatrix<ScalarType> &jacobian) const;
672
673 /** @} */
674 };
675
676 } // namespace AD
677 } // namespace Differentiation
678
679
680
681 /* --------------------- inline and template functions --------------------- */
682
683
684 #ifndef DOXYGEN
685
686 namespace Differentiation
687 {
688 namespace AD
689 {
690 # ifdef DEAL_II_WITH_ADOLC
691
692 /**
693 * Specialization for taped ADOL-C auto-differentiable numbers.
694 */
695 template <typename ADNumberType>
696 struct Types<ADNumberType,
697 std::enable_if_t<ADNumberTraits<ADNumberType>::type_code ==
698 NumberTypes::adolc_taped>>
699 {
700 /**
701 * Typedef for tape indices. ADOL-C uses short integers, so
702 * we restrict ourselves to similar types.
703 */
704 using tape_index = unsigned short;
705
706 /**
707 * Typedef for tape buffer sizes.
708 */
709 using tape_buffer_sizes = unsigned int;
710 }; // struct Types
711
712
713 /**
714 * Specialization for taped ADOL-C auto-differentiable numbers.
715 */
716 template <typename ADNumberType>
717 struct Numbers<ADNumberType,
718 std::enable_if_t<ADNumberTraits<ADNumberType>::type_code ==
719 NumberTypes::adolc_taped>>
720 {
721 /**
722 * A tape index that is unusable and can be used to invalidate recording
723 * operations.
724 *
725 * @note ADOL-C doesn't allow us to record to this reserved tape (i.e. can't
726 * write it to file), so we can safely use it as an invalidation case. In
727 * general, we want the user to be able to record to a tape if they'd
728 * like.
729 */
730 static const typename Types<ADNumberType>::tape_index invalid_tape_index =
731 0;
732
733 /**
734 * The maximum number of tapes that can be written on one process.
735 */
736 // Note: This value is a limitation of ADOL-C, and not something that we
737 // have control over. See test adolc/helper_tape_index_01.cc for
738 // verification that we cannot use or exceed this value. This value is
739 // defined as TBUFNUM; see
740 // https://gitlab.com/adol-c/adol-c/blob/master/ADOL-C/include/adolc/internal/usrparms.h#L34
741 # ifdef __clang__
742 static const typename Types<ADNumberType>::tape_index max_tape_index =
743 TBUFNUM;
744 # else
745 // For some reason, the test adolc/helper_tape_index_01 indicates that
746 // ADOL-C does not reliably perform correct computations for the full
747 // range of tape indices when GCC is the compiler. So we limit this number
748 // according to the results of the test.
749 static const typename Types<ADNumberType>::tape_index max_tape_index =
750 TBUFNUM - 2;
751 # endif
752 }; // struct Numbers
753
754
755 /**
756 * Specialization for taped ADOL-C auto-differentiable numbers.
757 *
758 * Note: In the case of ADOL-C taped numbers, the associated scalar
759 * type is always expected to be a double. So we need to make a further
760 * specialization when ScalarType is a float.
761 */
762 template <typename ADNumberType>
763 struct TapedDrivers<
764 ADNumberType,
765 double,
766 std::enable_if_t<ADNumberTraits<ADNumberType>::type_code ==
767 NumberTypes::adolc_taped>>
768 {
769 using scalar_type = double;
770
771 /**
772 * Constructor
773 */
774 TapedDrivers();
775
776
777 /**
778 * @name Taping
779 * @{
780 */
781
782 bool
783 is_recording() const;
784
785 typename Types<ADNumberType>::tape_index
786 active_tape_index() const;
787
788 bool
789 keep_independent_values() const;
790
791 bool
792 is_registered_tape(
793 const typename Types<ADNumberType>::tape_index tape_index) const;
794
795 void
796 set_tape_buffer_sizes(
797 const typename Types<ADNumberType>::tape_buffer_sizes in_obufsize,
798 const typename Types<ADNumberType>::tape_buffer_sizes in_lbufsize,
799 const typename Types<ADNumberType>::tape_buffer_sizes in_vbufsize,
800 const typename Types<ADNumberType>::tape_buffer_sizes in_tbufsize);
801
802 void
803 start_taping(const typename Types<ADNumberType>::tape_index tape_index,
804 const bool keep_independent_values);
805
806 void
807 stop_taping(
808 const typename Types<ADNumberType>::tape_index active_tape_index,
809 const bool write_tapes_to_file);
810
811 std::vector<typename Types<ADNumberType>::tape_index>
812 get_registered_tape_indices() const;
813
814 void
815 activate_tape(const typename Types<ADNumberType>::tape_index tape_index);
816
817 bool
818 requires_retaping(
819 const typename Types<ADNumberType>::tape_index tape_index) const;
820
821 bool
822 last_action_requires_retaping() const;
823
824 void
825 remove_tape(const typename Types<ADNumberType>::tape_index tape_index);
826
827 void
828 reset(const bool clear_registered_tapes);
829
830 void
831 print(std::ostream &stream) const;
832
833 void
834 print_tape_stats(
835 const typename Types<ADNumberType>::tape_index tape_index,
836 std::ostream &stream) const;
837
838 /** @} */
839
840 /**
841 * @name Drivers for scalar functions (one dependent variable)
842 * @{
843 */
844
845 scalar_type
846 value(const typename Types<ADNumberType>::tape_index active_tape_index,
847 const std::vector<scalar_type> &independent_variables) const;
848
849 void
850 gradient(const typename Types<ADNumberType>::tape_index active_tape_index,
851 const std::vector<scalar_type> &independent_variables,
852 Vector<scalar_type> &gradient) const;
853
854 void
855 hessian(const typename Types<ADNumberType>::tape_index active_tape_index,
856 const std::vector<scalar_type> &independent_variables,
857 FullMatrix<scalar_type> &hessian) const;
858
859 /** @} */
860
861 /**
862 * @name Drivers for vector functions (multiple dependent variables)
863 * @{
864 */
865
866 void
867 values(const typename Types<ADNumberType>::tape_index active_tape_index,
868 const unsigned int n_dependent_variables,
869 const std::vector<scalar_type> &independent_variables,
870 Vector<scalar_type> &values) const;
871
872 void
873 jacobian(const typename Types<ADNumberType>::tape_index active_tape_index,
874 const unsigned int n_dependent_variables,
875 const std::vector<scalar_type> &independent_variables,
876 FullMatrix<scalar_type> &jacobian) const;
877
878 /** @} */
879
880 protected:
881 /**
882 * Index of the tape that is currently in use. It is this tape that will
883 * be recorded to or read from when performing computations using "taped"
884 * auto-differentiable numbers.
885 */
886 typename Types<ADNumberType>::tape_index active_tape;
887
888 /**
889 * Mark whether we're going to inform taped data structures to retain
890 * the coefficients ("Taylors" in ADOL-C nomenclature) stored on the
891 * tape so that they can be evaluated again at a later stage.
892 */
893 bool keep_values;
894
895 /**
896 * Mark whether we're currently recording a tape. Dependent on the state
897 * of this flag, only a restricted set of operations are allowable.
898 */
899 bool is_recording_flag;
900
901 /**
902 * The status of the last function or derivative evaluation performed on
903 * the selected tape. As quoted from the ADOL-C manual, this can take
904 * on one of six different values with the following interpretation:
905 *
906 * - <b>+3:</b> The function is locally analytic.
907 * - <b>+2:</b> The function is locally analytic but the sparsity
908 * structure (compared to the situation at the taping point) may have
909 * changed, e.g. while at taping arguments <code>fmax(a,b)</code>
910 * returned <code>a</code>, we get <code>b</code> at the argument
911 * currently used.
912 * - <b>+1:</b> At least one of the functions <code>fmin</code>,
913 * <code>fmax</code> or <code>fabs</code> is evaluated at a tie or
914 * zero, respectively. Hence, the function to be differentiated is
915 * Lipschitz-continuous but possibly non-differentiable.
916 * - <b>0:</b> Some arithmetic comparison involving adoubles yields a
917 * tie. Hence, the function to be differentiated may be discontinuous.
918 * - <b>-1:</b> An <code>adouble</code> comparison yields different
919 * results from the evaluation point at which the tape was generated.
920 * - <b>-2:</b> The argument of a user-defined quadrature has changed from
921 * the evaluation point at which the tape was generated.
922 *
923 * When the @p status variable takes a negative value, retaping of the dependent
924 * function is necessary for a reliable computation to be performed.
925 * This status can be queried through the requires_retaping() and
926 * last_action_requires_retaping() functions.
927 */
928 mutable std::map<typename Types<ADNumberType>::tape_index, int> status;
929
930 /**
931 * A flag indicating that we should preferentially use the user-defined
932 * taped buffer sizes as opposed to either the default values selected
933 * by the AD library (or, in the case of ADOL-C, defined in an
934 * ".adolcrc" file).
935 */
936 bool use_stored_taped_buffer_sizes;
937
938 /**
939 * ADOL-C operations buffer size.
940 */
941 typename Types<ADNumberType>::tape_buffer_sizes obufsize;
942
943 /**
944 * ADOL-C locations buffer size.
945 */
946 typename Types<ADNumberType>::tape_buffer_sizes lbufsize;
947
948 /**
949 * ADOL-C value buffer size.
950 */
951 typename Types<ADNumberType>::tape_buffer_sizes vbufsize;
952
953 /**
954 * ADOL-C Taylor buffer size.
955 */
956 typename Types<ADNumberType>::tape_buffer_sizes tbufsize;
957 };
958
959 # else
960
961 /**
962 * Specialization for taped ADOL-C auto-differentiable numbers.
963 *
964 * Although we could revert to the default definition for the
965 * unspecialized TapedDrivers class, we add this specialization
966 * to provide a more descriptive error message if any of its
967 * member functions are called.
968 */
969 template <typename ADNumberType>
970 struct TapedDrivers<
971 ADNumberType,
972 double,
973 std::enable_if_t<ADNumberTraits<ADNumberType>::type_code ==
974 NumberTypes::adolc_taped>>
975 {
976 using scalar_type = double;
977
978 /**
979 * @name Taping
980 * @{
981 */
982
983 bool
984 is_recording() const;
985
986 typename Types<ADNumberType>::tape_index
987 active_tape_index() const;
988
989 bool
990 keep_independent_values() const;
991
992 bool
993 is_registered_tape(
994 const typename Types<ADNumberType>::tape_index tape_index) const;
995
996 void
997 set_tape_buffer_sizes(
998 const typename Types<ADNumberType>::tape_buffer_sizes,
999 const typename Types<ADNumberType>::tape_buffer_sizes,
1000 const typename Types<ADNumberType>::tape_buffer_sizes,
1001 const typename Types<ADNumberType>::tape_buffer_sizes);
1002
1003 void
1004 start_taping(const typename Types<ADNumberType>::tape_index, const bool);
1005
1006 void
1007 stop_taping(const typename Types<ADNumberType>::tape_index, const bool);
1008
1009 std::vector<typename Types<ADNumberType>::tape_index>
1010 get_registered_tape_indices() const;
1011
1012 void
1013 activate_tape(const typename Types<ADNumberType>::tape_index);
1014
1015 bool
1016 requires_retaping(const typename Types<ADNumberType>::tape_index) const;
1017
1018 bool
1019 last_action_requires_retaping() const;
1020
1021 void
1022 remove_tape(const typename Types<ADNumberType>::tape_index);
1023
1024 void
1025 reset(const bool);
1026
1027 void
1028 print(std::ostream &stream) const;
1029
1030 void
1031 print_tape_stats(const typename Types<ADNumberType>::tape_index,
1032 std::ostream &) const;
1033
1034 /** @} */
1035
1036 /**
1037 * @name Drivers for scalar functions (one dependent variable)
1038 * @{
1039 */
1040
1041 scalar_type
1042 value(const typename Types<ADNumberType>::tape_index,
1043 const std::vector<scalar_type> &) const;
1044
1045 void
1046 gradient(const typename Types<ADNumberType>::tape_index,
1047 const std::vector<scalar_type> &,
1048 Vector<scalar_type> &) const;
1049
1050 void
1051 hessian(const typename Types<ADNumberType>::tape_index,
1052 const std::vector<scalar_type> &,
1053 FullMatrix<scalar_type> &) const;
1054
1055 /** @} */
1056
1057 /**
1058 * @name Drivers for vector functions (multiple dependent variables)
1059 * @{
1060 */
1061
1062 void
1063 values(const typename Types<ADNumberType>::tape_index,
1064 const unsigned int,
1065 const std::vector<scalar_type> &,
1066 Vector<scalar_type> &) const;
1067
1068 void
1069 jacobian(const typename Types<ADNumberType>::tape_index,
1070 const unsigned int,
1071 const std::vector<scalar_type> &,
1072 FullMatrix<scalar_type> &) const;
1073
1074 /** @} */
1075 };
1076
1077 # endif // DEAL_II_WITH_ADOLC
1078
1079 /**
1080 * Specialization for ADOL-C taped numbers. It is expected that the
1081 * scalar return type for this class is a float.
1082 *
1083 * @note ADOL-C only has drivers for doubles, and so floats are
1084 * not intrinsically supported. This wrapper struct works around
1085 * the issue when necessary.
1086 */
1087 template <typename ADNumberType>
1088 struct TapedDrivers<
1089 ADNumberType,
1090 float,
1091 std::enable_if_t<ADNumberTraits<ADNumberType>::type_code ==
1092 NumberTypes::adolc_taped>>
1093 {
1094 using scalar_type = float;
1095
1096 /**
1097 * @name Taping
1098 * @{
1099 */
1100
1101 bool
1102 is_recording() const;
1103
1104 typename Types<ADNumberType>::tape_index
1105 active_tape_index() const;
1106
1107 bool
1108 keep_independent_values() const;
1109
1110 bool
1111 is_registered_tape(
1112 const typename Types<ADNumberType>::tape_index tape_index) const;
1113
1114 void
1115 set_tape_buffer_sizes(
1116 const typename Types<ADNumberType>::tape_buffer_sizes obufsize,
1117 const typename Types<ADNumberType>::tape_buffer_sizes lbufsize,
1118 const typename Types<ADNumberType>::tape_buffer_sizes vbufsize,
1119 const typename Types<ADNumberType>::tape_buffer_sizes tbufsize);
1120
1121 void
1122 start_taping(const typename Types<ADNumberType>::tape_index tape_index,
1123 const bool keep_independent_values);
1124
1125 void
1126 stop_taping(
1127 const typename Types<ADNumberType>::tape_index active_tape_index,
1128 const bool write_tapes_to_file);
1129
1130 std::vector<typename Types<ADNumberType>::tape_index>
1131 get_registered_tape_indices() const;
1132
1133 void
1134 activate_tape(const typename Types<ADNumberType>::tape_index tape_index);
1135
1136 bool
1137 requires_retaping(
1138 const typename Types<ADNumberType>::tape_index tape_index) const;
1139
1140 bool
1141 last_action_requires_retaping() const;
1142
1143 void
1144 remove_tape(const typename Types<ADNumberType>::tape_index tape_index);
1145
1146 void
1147 reset(const bool clear_registered_tapes);
1148
1149 void
1150 print(std::ostream &stream) const;
1151
1152 void
1153 print_tape_stats(
1154 const typename Types<ADNumberType>::tape_index tape_index,
1155 std::ostream &stream) const;
1156
1157 /** @} */
1158
1159 /**
1160 * @name Drivers for scalar functions (one dependent variable)
1161 * @{
1162 */
1163
1164 scalar_type
1165 value(const typename Types<ADNumberType>::tape_index active_tape_index,
1166 const std::vector<scalar_type> &independent_variables) const;
1167
1168 void
1169 gradient(const typename Types<ADNumberType>::tape_index active_tape_index,
1170 const std::vector<scalar_type> &independent_variables,
1171 Vector<scalar_type> &gradient) const;
1172
1173 void
1174 hessian(const typename Types<ADNumberType>::tape_index active_tape_index,
1175 const std::vector<scalar_type> &independent_variables,
1176 FullMatrix<scalar_type> &hessian) const;
1177
1178 /** @} */
1179
1180 /**
1181 * @name Drivers for vector functions (multiple dependent variables)
1182 * @{
1183 */
1184
1185 void
1186 values(const typename Types<ADNumberType>::tape_index active_tape_index,
1187 const unsigned int n_dependent_variables,
1188 const std::vector<scalar_type> &independent_variables,
1189 Vector<scalar_type> &values) const;
1190
1191 void
1192 jacobian(const typename Types<ADNumberType>::tape_index active_tape_index,
1193 const unsigned int n_dependent_variables,
1194 const std::vector<scalar_type> &independent_variables,
1195 FullMatrix<scalar_type> &jacobian) const;
1196
1197 /** @} */
1198
1199 private:
1200 /**
1201 * Copy a vector of floats into a vector of doubles
1202 */
1203 std::vector<double>
1204 vector_float_to_double(const std::vector<float> &in) const;
1205
1206 /**
1207 * The object that actually takes care of the taping
1208 */
1209 TapedDrivers<ADNumberType, double> taped_driver;
1210 };
1211
1212
1213 // ------------- TapelessDrivers -------------
1214
1215
1216 /**
1217 * Specialization for auto-differentiable numbers that use
1218 * reverse mode to compute the first derivatives (and, if supported,
1219 * forward mode for the second).
1220 */
1221 template <typename ADNumberType, typename ScalarType>
1222 struct TapelessDrivers<
1223 ADNumberType,
1224 ScalarType,
1225 std::enable_if_t<ADNumberTraits<ADNumberType>::type_code ==
1226 NumberTypes::sacado_rad ||
1227 ADNumberTraits<ADNumberType>::type_code ==
1228 NumberTypes::sacado_rad_dfad>>
1229 {
1230 /**
1231 * Constructor
1232 */
1233 TapelessDrivers();
1234
1235 /**
1236 * @name Configuration
1237 * @{
1238 */
1239
1240 static void
1241 initialize_global_environment(const unsigned int n_independent_variables);
1242
1243 /** @} */
1244
1245 /**
1246 * @name Operation status
1247 * @{
1248 */
1249
1250 void
1251 allow_dependent_variable_marking();
1252
1253 void
1254 prevent_dependent_variable_marking();
1255
1256 bool
1257 is_dependent_variable_marking_allowed() const;
1258
1259 /** @} */
1260
1261 /**
1262 * @name Drivers for scalar functions
1263 * @{
1264 */
1265
1266 ScalarType
1267 value(const std::vector<ADNumberType> &dependent_variables) const;
1268
1269 void
1270 gradient(const std::vector<ADNumberType> &independent_variables,
1271 const std::vector<ADNumberType> &dependent_variables,
1272 Vector<ScalarType> &gradient) const;
1273
1274 void
1275 hessian(const std::vector<ADNumberType> &independent_variables,
1276 const std::vector<ADNumberType> &dependent_variables,
1277 FullMatrix<ScalarType> &hessian) const;
1278
1279 /** @} */
1280
1281 /**
1282 * @name Drivers for vector functions
1283 * @{
1284 */
1285
1286 void
1287 values(const std::vector<ADNumberType> &dependent_variables,
1288 Vector<ScalarType> &values) const;
1289
1290 void
1291 jacobian(const std::vector<ADNumberType> &independent_variables,
1292 const std::vector<ADNumberType> &dependent_variables,
1293 FullMatrix<ScalarType> &jacobian) const;
1294
1295 /** @} */
1296
1297 private:
1298 /**
1299 * A flag that states whether or not dependent variables can be marked
1300 * within the current phase of operations.
1301 */
1302 bool dependent_variable_marking_safe;
1303 };
1304
1305
1306 /**
1307 * Specialization for auto-differentiable numbers that use
1308 * forward mode to compute the first (and, if supported, second)
1309 * derivatives.
1310 */
1311 template <typename ADNumberType, typename ScalarType>
1312 struct TapelessDrivers<
1313 ADNumberType,
1314 ScalarType,
1315 std::enable_if_t<ADNumberTraits<ADNumberType>::type_code ==
1316 NumberTypes::adolc_tapeless ||
1317 ADNumberTraits<ADNumberType>::type_code ==
1318 NumberTypes::sacado_dfad ||
1319 ADNumberTraits<ADNumberType>::type_code ==
1320 NumberTypes::sacado_dfad_dfad>>
1321 {
1322 /**
1323 * Constructor
1324 */
1325 TapelessDrivers();
1326
1327 /**
1328 * @name Configuration
1329 * @{
1330 */
1331
1332 static void
1333 initialize_global_environment(const unsigned int n_independent_variables);
1334
1335 /** @} */
1336
1337 /**
1338 * @name Operation status
1339 * @{
1340 */
1341
1342 void
1343 allow_dependent_variable_marking();
1344
1345 void
1346 prevent_dependent_variable_marking();
1347
1348 bool
1349 is_dependent_variable_marking_allowed() const;
1350
1351 /** @} */
1352
1353 /**
1354 * @name Drivers for scalar functions
1355 * @{
1356 */
1357
1358 ScalarType
1359 value(const std::vector<ADNumberType> &dependent_variables) const;
1360
1361 void
1362 gradient(const std::vector<ADNumberType> &independent_variables,
1363 const std::vector<ADNumberType> &dependent_variables,
1364 Vector<ScalarType> &gradient) const;
1365
1366 void
1367 hessian(const std::vector<ADNumberType> &independent_variables,
1368 const std::vector<ADNumberType> &dependent_variables,
1369 FullMatrix<ScalarType> &hessian) const;
1370
1371 /** @} */
1372
1373 /**
1374 * @name Drivers for vector functions
1375 * @{
1376 */
1377
1378 void
1379 values(const std::vector<ADNumberType> &dependent_variables,
1380 Vector<ScalarType> &values) const;
1381
1382 void
1383 jacobian(const std::vector<ADNumberType> &independent_variables,
1384 const std::vector<ADNumberType> &dependent_variables,
1385 FullMatrix<ScalarType> &jacobian) const;
1386
1387 /** @} */
1388
1389 private:
1390 /**
1391 * A flag that states whether or not dependent variables can be marked
1392 * within the current phase of operations.
1393 */
1394 bool dependent_variable_marking_safe;
1395 };
1396
1397 } // namespace AD
1398 } // namespace Differentiation
1399
1400
1401 #endif // DOXYGEN
1402
1403 DEAL_II_NAMESPACE_CLOSE
1404
1405
1406 #endif