Debian Codegraph @

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

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2017 - 2024 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_number_traits_h
16 #define dealii_differentiation_ad_ad_number_traits_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/exceptions.h>
21 #include <deal.II/base/numbers.h>
22
23 #include <deal.II/differentiation/ad/ad_number_types.h>
24
25 #include <boost/type_traits.hpp>
26
27 #include <complex>
28 #include <type_traits>
29
30 DEAL_II_NAMESPACE_OPEN
31
32 namespace Differentiation
33 {
34 namespace AD
35 {
36 /**
37 * A number traits class to help describe some characteristic
38 * information about auto-differentiable numbers.
39 *
40 * @tparam ScalarType A real or complex floating point number.
41 * @tparam ADNumberTypeCode An enumeration specifying the type
42 * code for the supported auto-differentiable counterpart
43 * to the given @p ScalarType.
44 * @tparam T An arbitrary type resulting from the application of
45 * the SFINAE idiom to selectively specialize this class.
46 */
47 template <typename ScalarType,
48 enum NumberTypes ADNumberTypeCode,
49 typename T = void>
50 struct NumberTraits;
51
52
53
54 /**
55 * A number traits class to help describe some characteristic
56 * information about auto-differentiable numbers. This class is only
57 * specialized (and, therefore, only made constructible) if the
58 * @p ADNumberType template parameter is indeed a supported
59 * auto-differentiable number.
60 *
61 * @tparam ADNumberType A type corresponding to a supported
62 * auto-differentiable number.
63 * @tparam T An arbitrary type resulting from the application of
64 * the SFINAE idiom to selectively specialize this class.
65 */
66 template <typename ADNumberType, typename T = void>
67 struct ADNumberTraits;
68
69
70 /**
71 * This namespace defines the classes that help provide a unified interface
72 * to all auto-differentiation numbers.
73 */
74 namespace internal
75 {
76 // The following three classes, namely ADNumberInfoFromEnum, Marking, and
77 // ExtractData, are those that need to be implemented for each new
78 // auto-differentiable number type. This information is then used by
79 // NumberTraits and ADNumberTraits to provide a uniform interface, as used
80 // by our drivers, to the underlying number types.
81
82
83 /**
84 * A struct that defines some fundamental information about a
85 * auto-differentiable number based on the @p ScalarType and the
86 * AD-enumeration selected by @p ADNumberTypeCode. This information is
87 * used in other convenience classes and templated functions to
88 * automatically determine information about the auto-differentiable
89 * number that has been selected to wrap the @p ScalarType.
90 *
91 * The specializations of this class have to implement the following
92 * member data and type definitions:
93 * @code
94 *
95 * // State whether the auto-differentiable number uses taping or not.
96 * static const bool is_taped;
97 * // The real-type for the auto-differentiable number
98 * using real_type = <ADNumberType>;
99 * // The type of number returned when taking the first derivative of the @p real_type.
100 * using derivative_type = <Scalar/ADNumberType>;
101 * // The number of derivative levels computable from the @p real_type.
102 * static const unsigned int n_supported_derivative_levels;
103 *
104 * @endcode
105 */
106 template <typename ScalarType,
107 enum NumberTypes ADNumberTypeCode,
108 typename = void>
109 struct ADNumberInfoFromEnum;
110
111
112 /**
113 * A struct to assist with the marking of AD numbers that represent
114 * independent and dependent variables.
115 *
116 * The specializations of this class have to implement the following
117 * member functions:
118 * @code
119 *
120 * // Initialize the state of an independent variable.
121 * static void
122 * independent_variable(const ScalarType &in,
123 * const unsigned int index,
124 * const unsigned int n_independent_variables,
125 * ADNumberType &out)
126 *
127 * // Initialize the state of a dependent variable.
128 * static void
129 * dependent_variable(ADNumberType &out,
130 * const ADNumberType &func);
131 *
132 * @endcode
133 * where @p ADNumberType is the auto-differentiable number type and
134 * @p ScalarType is its floating point counterpart.
135 *
136 * @tparam ADNumberType A type corresponding to a supported
137 * auto-differentiable number.
138 * @tparam T An arbitrary type resulting from the application of
139 * the SFINAE idiom to selectively specialize this class.
140 */
141 template <typename ADNumberType, typename T = void>
142 struct Marking;
143
144
145 /**
146 * A struct to help extract certain information associated with
147 * auto-differentiable numbers.
148 *
149 * The specializations of this class have to implement the following
150 * member data and type definitions:
151 * @code
152 *
153 * // Extract the real scalar value.
154 * static scalar_type
155 * value (const ADNumberType &x);
156 *
157 * // Extract the number of directional derivatives.
158 * static unsigned int
159 * n_directional_derivatives (const ADNumberType &x);
160 *
161 * // Extract the directional derivative in the specified @p direction.
162 * static derivative_type
163 * directional_derivative (const ADNumberType &x,
164 * const unsigned int direction);
165 *
166 * @endcode
167 * where @p ADNumberType is the auto-differentiable number type.
168 *
169 * @tparam ADNumberType A type corresponding to a supported
170 * auto-differentiable number.
171 * @tparam T An arbitrary type resulting from the application of
172 * the SFINAE idiom to selectively specialize this class.
173 */
174 template <typename ADNumberType, typename T = void>
175 struct ExtractData;
176
177
178 /**
179 * A struct that checks that the data expected to be stored in a
180 * specialization of the ADNumberInfoFromEnum struct has been supplied. By
181 * default it is assumed that the input type does not satisfy the
182 * necessary conditions to construct this class.
183 *
184 * @tparam ADNumberTrait A class that examined whether it contains the necessary
185 * information to satisfy the requirements for being an internally
186 * supported auto-differentiable number.
187 * @tparam T An arbitrary type resulting from the application of
188 * the SFINAE idiom to selectively specialize this class.
189 */
190 template <typename ADNumberTrait, typename T = void>
191 struct HasRequiredADInfo;
192
193
194 /**
195 * Provide a convenience function to assist in the casting of some
196 * number types to other number types. On top of the standard class
197 * definition given in @p base/numbers.h , this extension allows the
198 * conversion of automatic-differentiation numbers to generic floats.
199 *
200 * This is necessary because ADOL-C doesn't provide a convenient
201 * way to convert from an @p ADNumberType to floats (@p T) other than
202 * the real-type equivalent that its associated with. For Sacado, and
203 * likely other AD number types, the floating point value stored in
204 * an @p ADNumberType must be extracted through some function that is
205 * specific to each type of AD number. This requires some specialist
206 * intervention to get at this data.
207 */
208 template <typename T>
209 struct NumberType;
210
211
212 /**
213 * A small struct to remove the @p std::complex wrapper
214 * around a number.
215 */
216 template <typename Number>
217 struct RemoveComplexWrapper;
218
219 } // namespace internal
220
221
222 /**
223 * A struct to indicate whether a given @p NumberType is a supported
224 * auto-differentiable number or not. By default, numbers are not
225 * considered to have the necessary characteristics to fulfill this
226 * condition.
227 */
228 template <typename NumberType>
229 struct is_ad_number;
230
231
232 /**
233 * A struct to indicate whether a given @p NumberType is a taped
234 * auto-differentiable number or not. By default, numbers are not
235 * considered to have the necessary characteristics to fulfill this
236 * condition.
237 */
238 template <typename NumberType, typename = void>
239 struct is_taped_ad_number;
240
241
242 /**
243 * A struct to indicate whether a given @p NumberType is a tapeless
244 * auto-differentiable number or not. By default, numbers are not
245 * considered to have the necessary characteristics to fulfill this
246 * condition.
247 */
248 template <typename NumberType, typename = void>
249 struct is_tapeless_ad_number;
250
251
252 /**
253 * A struct to indicate whether a given @p NumberType is a real-valued
254 * auto-differentiable number or not. By default, numbers are not
255 * considered to have the necessary characteristics to fulfill this
256 * condition.
257 */
258 template <typename NumberType, typename = void>
259 struct is_real_valued_ad_number;
260
261
262 /**
263 * A struct to indicate whether a given @p NumberType is a complex-valued
264 * auto-differentiable number or not. By default, numbers are not
265 * considered to have the necessary characteristics to fulfill this
266 * condition.
267 */
268 template <typename NumberType, typename = void>
269 struct is_complex_valued_ad_number;
270
271 } // namespace AD
272 } // namespace Differentiation
273
274
275 /* ----------- inline and template functions and specializations ----------- */
276
277
278 #ifndef DOXYGEN
279
280
281 namespace Differentiation
282 {
283 namespace AD
284 {
285 namespace internal
286 {
287 template <typename ADNumberTrait, typename>
288 struct HasRequiredADInfo : std::false_type
289 {};
290
291
292 /**
293 * Specialization to detect whether the input AD number
294 * is internally supported or not. In particular, we
295 * check to see that it is not an floating point type, that it
296 * has been assigned a type_code and has other basic
297 * characteristics necessary for the internal interface of
298 * the AD drivers.
299 *
300 * The implementation of this struct follows this suggestion:
301 * https://stackoverflow.com/a/16000226
302 */
303 template <typename ADNumberTrait>
304 struct HasRequiredADInfo<
305 ADNumberTrait,
306 decltype((void)ADNumberTrait::type_code,
307 (void)ADNumberTrait::is_taped,
308 (void)std::declval<typename ADNumberTrait::real_type>(),
309 (void)std::declval<typename ADNumberTrait::derivative_type>(),
310 void())>
311 : std::conditional_t<
312 std::is_floating_point_v<typename ADNumberTrait::real_type>,
313 std::false_type,
314 std::true_type>
315 {};
316
317
318 /**
319 * A specialization for the information struct for arithmetic / floating
320 * point numbers.
321 */
322 template <typename ScalarType>
323 struct ADNumberInfoFromEnum<
324 ScalarType,
325 Differentiation::AD::NumberTypes::none,
326 std::enable_if_t<std::is_floating_point_v<ScalarType>>>
327 {
328 static const bool is_taped = false;
329 using real_type = ScalarType;
330 using derivative_type = ScalarType;
331 static const unsigned int n_supported_derivative_levels = 0;
332 };
333
334
335 /**
336 * A dummy specialization for floating point numbers. This is helpful
337 * for nested auto-differentiable numbers, where a recursive marking
338 * mechanism can be employed (e.g. Sacado types).
339 */
340 template <typename ScalarType>
341 struct Marking<ScalarType,
342 std::enable_if_t<std::is_floating_point_v<ScalarType>>>
343 {
344 /**
345 * Initialize the state of an independent variable.
346 *
347 * With a nested marking approach it is sometimes
348 * necessary to initialize the value of an intermediate
349 * value that may be a floating point number.
350 */
351 template <typename ADNumberType>
352 static void
353 independent_variable(const ScalarType &in,
354 const unsigned int,
355 const unsigned int,
356 ADNumberType &out)
357 {
358 out = in;
359 }
360
361 /*
362 * Initialize the state of a dependent variable.
363 */
364 template <typename ADNumberType>
365 static void
366 dependent_variable(ADNumberType &, const ScalarType &)
367 {
368 AssertThrow(
369 false,
370 ExcMessage(
371 "Floating point numbers cannot be marked as dependent variables."));
372 }
373 };
374
375
376 /**
377 * A specialization of the marking strategy for complex numbers.
378 */
379 template <typename ADNumberType>
380 struct Marking<ADNumberType,
381 std::enable_if_t<boost::is_complex<ADNumberType>::value>>
382 {
383 /*
384 * Initialize the state of an independent variable.
385 */
386 template <typename ScalarType>
387 static void
388 independent_variable(const ScalarType &in,
389 const unsigned int,
390 const unsigned int,
391 ADNumberType &out)
392 {
393 AssertThrow(
394 false,
395 ExcMessage(
396 "Marking for complex numbers has not yet been implemented."));
397 out = in;
398 }
399
400 /*
401 * Initialize the state of a dependent variable.
402 */
403 template <typename ScalarType>
404 static void
405 dependent_variable(ADNumberType &, const ScalarType &)
406 {
407 AssertThrow(
408 false,
409 ExcMessage(
410 "Marking for complex numbers has not yet been implemented."));
411 }
412 };
413
414 } // namespace internal
415
416
417 template <typename NumberType, typename>
418 struct is_taped_ad_number : std::false_type
419 {};
420
421
422 template <typename NumberType, typename>
423 struct is_tapeless_ad_number : std::false_type
424 {};
425
426
427 template <typename NumberType, typename>
428 struct is_real_valued_ad_number : std::false_type
429 {};
430
431
432 template <typename NumberType, typename>
433 struct is_complex_valued_ad_number : std::false_type
434 {};
435
436
437 /**
438 * We use the specialization of the HasRequiredADInfo struct
439 * to ensure that only internally supported numbers are
440 * considered AD numbers.
441 */
442 template <typename NumberType>
443 struct is_ad_number
444 : internal::HasRequiredADInfo<ADNumberTraits<std::decay_t<NumberType>>>
445 {};
446
447
448 /**
449 * Specialization of the struct for the case when the input template
450 * parameter is a (real or complex) taped auto-differentiable number.
451 */
452 template <typename NumberType>
453 struct is_taped_ad_number<
454 NumberType,
455 std::enable_if_t<ADNumberTraits<std::decay_t<NumberType>>::is_taped>>
456 : std::true_type
457 {};
458
459
460 /**
461 * Specialization of the struct for the case when the input template
462 * parameter is a (real or complex) tapeless auto-differentiable number.
463 */
464 template <typename NumberType>
465 struct is_tapeless_ad_number<
466 NumberType,
467 std::enable_if_t<ADNumberTraits<std::decay_t<NumberType>>::is_tapeless>>
468 : std::true_type
469 {};
470
471
472 /**
473 * Specialization of the struct for the case when the input template
474 * parameter is a (taped or tapeless) real-valued auto-differentiable
475 * number.
476 */
477 template <typename NumberType>
478 struct is_real_valued_ad_number<
479 NumberType,
480 std::enable_if_t<
481 ADNumberTraits<std::decay_t<NumberType>>::is_real_valued>>
482 : std::true_type
483 {};
484
485
486 /**
487 * Specialization of the struct for the case when the input template
488 * parameter is a (taped or tapeless) complex-valued auto-differentiable
489 * number.
490 */
491 template <typename NumberType>
492 struct is_complex_valued_ad_number<
493 NumberType,
494 std::enable_if_t<
495 ADNumberTraits<std::decay_t<NumberType>>::is_complex_valued>>
496 : std::true_type
497 {};
498
499
500 namespace internal
501 {
502 /**
503 * Specialization of the selection struct which sets the type as being
504 * one that is the value type of the underlying complex number.
505 */
506 template <typename Number>
507 struct RemoveComplexWrapper
508 {
509 using type = Number;
510 };
511
512
513 /**
514 * Specialization of the selection struct which sets the value type
515 * to that resulting from the recursive removal of the complex
516 * number wrapper.
517 */
518 template <typename Number>
519 struct RemoveComplexWrapper<std::complex<Number>>
520 {
521 using type = typename RemoveComplexWrapper<Number>::type;
522 };
523
524
525 /**
526 * A dummy specialization for floating point numbers. This is helpful
527 * for nested auto-differentiable numbers, where a recursive marking
528 * mechanism can be employed (e.g. Sacado types).
529 */
530 template <typename NumberType>
531 struct ExtractData<NumberType,
532 std::enable_if_t<std::is_floating_point_v<NumberType>>>
533 {
534 /**
535 * Extract the floating point value.
536 */
537 static const NumberType &
538 value(const NumberType &x)
539 {
540 return x;
541 }
542
543
544 /**
545 * Extract the number of directional derivatives.
546 */
547 static unsigned int
548 n_directional_derivatives(const NumberType &)
549 {
550 return 0;
551 }
552
553
554 /**
555 * Extract the directional derivative in the specified @p direction.
556 */
557 static NumberType
558 directional_derivative(const NumberType &, const unsigned int)
559 {
560 return 0.0;
561 }
562 };
563
564
565
566 /**
567 * A struct specialization to help extract certain information associated
568 * with complex auto-differentiable numbers.
569 */
570 template <typename ADNumberType>
571 struct ExtractData<std::complex<ADNumberType>>
572 {
573 static_assert(Differentiation::AD::is_ad_number<ADNumberType>::value,
574 "Expected an auto-differentiable number.");
575
576
577 /**
578 * Extract the floating point value.
579 */
580 static std::complex<typename ADNumberTraits<ADNumberType>::scalar_type>
581 value(const std::complex<ADNumberType> &x)
582 {
583 return std::complex<
584 typename ADNumberTraits<ADNumberType>::scalar_type>(
585 ExtractData<ADNumberType>::value(x.real()),
586 ExtractData<ADNumberType>::value(x.imag()));
587 }
588
589
590 /**
591 * Extract the number of directional derivatives.
592 */
593 static unsigned int
594 n_directional_derivatives(const std::complex<ADNumberType> &x)
595 {
596 return ExtractData<ADNumberType>::n_directional_derivatives(x.real());
597 }
598
599
600 /**
601 * Extract the directional derivative in the specified @p direction.
602 */
603 static std::complex<
604 typename ADNumberTraits<ADNumberType>::derivative_type>
605 directional_derivative(const std::complex<ADNumberType> &x,
606 const unsigned int direction)
607 {
608 return std::complex<
609 typename ADNumberTraits<ADNumberType>::derivative_type>(
610 ExtractData<ADNumberType>::directional_derivative(x.real(),
611 direction),
612 ExtractData<ADNumberType>::directional_derivative(x.imag(),
613 direction));
614 }
615 };
616
617
618 template <typename T>
619 struct NumberType
620 {
621 /**
622 * Standard number conversion
623 */
624 template <typename F>
625 static auto
626 value(const F &f, std::enable_if_t<!is_ad_number<F>::value> * = nullptr)
627 -> decltype(dealii::internal::NumberType<T>::value(f))
628 {
629 // We call the other function defined in the numbers
630 // header to take care of all of the usual cases.
631 return dealii::internal::NumberType<T>::value(f);
632 }
633
634 /**
635 * Conversion from an AD number to a scalar number.
636 * We wish to ensure that @p T is a scalar type because,
637 * in general, the conversion between AD numbers is either
638 * non-trivial or an invalid operation.
639 */
640 template <typename F>
641 static T
642 value(const F &f,
643 std::enable_if_t<is_ad_number<F>::value &&
644 std::is_floating_point_v<T>> * = nullptr)
645 {
646 // We recursively call this function in case the AD number is a
647 // nested one. The recursion ends when the extracted value is
648 // a floating point number.
649 return NumberType<T>::value(ExtractData<F>::value(f));
650 }
651
652 /**
653 * Conversion from an AD number another AD number.
654 *
655 * Since this is the most generic case we'll assume that
656 * the return type is constructible from the input type.
657 */
658 template <typename F>
659 static T
660 value(const F &f,
661 std::enable_if_t<is_ad_number<F>::value && is_ad_number<T>::value>
662 * = nullptr)
663 {
664 return T(f);
665 }
666 };
667
668 template <typename T>
669 struct NumberType<std::complex<T>>
670 {
671 /**
672 * Standard complex number conversion
673 */
674 template <typename F>
675 static auto
676 value(const F &f, std::enable_if_t<!is_ad_number<F>::value> * = nullptr)
677 -> decltype(dealii::internal::NumberType<std::complex<T>>::value(f))
678 {
679 // We call the other function defined in the numbers
680 // header to take care of all of the usual cases.
681 return dealii::internal::NumberType<std::complex<T>>::value(f);
682 }
683
684
685 /**
686 * Conversion from a complex AD number to another
687 * complex number templated on a scalar number.
688 */
689 template <typename F>
690 static std::complex<T>
691 value(const F &f,
692 std::enable_if_t<is_ad_number<F>::value &&
693 std::is_floating_point_v<T>> * = nullptr)
694 {
695 // We recursively call this function in case the AD number is a
696 // nested one. The recursion ends when the extracted value is
697 // a floating point number.
698 return std::complex<T>(
699 NumberType<T>::value(ExtractData<F>::value(f)));
700 }
701
702 template <typename F>
703 static std::complex<T>
704 value(const std::complex<F> &f)
705 {
706 // Deal with the two parts of the input complex
707 // number individually.
708 return std::complex<T>(NumberType<T>::value(f.real()),
709 NumberType<T>::value(f.imag()));
710 }
711 };
712
713 } // namespace internal
714
715
716
717 /**
718 * Specialization of the general NumberTraits class that
719 * provides relevant information for auto-differentiable numbers.
720 *
721 * For each new @p ADNumberTypeCode enumeration, a data structure called
722 * internal::ADNumberInfoFromEnum is to be defined, from which we require
723 * the following basic information determine all of the required information
724 * and type traits for our helper classes:
725 * - An alias called @p scalar_type, which defines the scalar or
726 * floating-point valued counterpart to the auto-differentiable number
727 * type. This can be real or complex valued.
728 * - An alias called @p derivative_type, which defines the
729 * number type for directional derivatives.
730 * - A boolean called @p is_taped, which defines whether the auto-differentiable
731 * number is a taped number or not.
732 *
733 * This specific version specializes the generic case where the template
734 * @p ScalarType represents a floating or complex number that is templated
735 * on a floating point type.
736 */
737 template <typename ScalarType, enum NumberTypes ADNumberTypeCode>
738 struct NumberTraits<
739 ScalarType,
740 ADNumberTypeCode,
741 std::enable_if_t<
742 std::is_floating_point_v<ScalarType> ||
743 (boost::is_complex<ScalarType>::value &&
744 std::is_floating_point_v<
745 typename internal::RemoveComplexWrapper<ScalarType>::type>)>>
746 {
747 /**
748 * The type of taping used
749 */
750 static constexpr enum NumberTypes type_code = ADNumberTypeCode;
751
752 // The clang compiler does not seem to like these
753 // variables being defined as constant expressions
754 // (the tests <adolc|sacado>/ad_number_traits_02 will
755 // fail with linking errors). However, GCC complains
756 // about the use of non-constant expressions in
757 // std::conditional.
758 # ifdef __clang__
759
760 /**
761 * A flag to indicate whether the number is of
762 * the taped variety or not
763 */
764 static const bool is_taped;
765
766
767 /**
768 * A flag to indicate whether the number is of
769 * the tapeless variety or not
770 */
771 static const bool is_tapeless;
772
773
774 /**
775 * A flag to indicate whether the number represents
776 * a real value
777 */
778 static const bool is_real_valued;
779
780
781 /**
782 * A flag to indicate whether the number represents
783 * a complex value
784 */
785 static const bool is_complex_valued;
786
787
788 /**
789 * The number of directional derivatives that can be
790 * taken with this auto-differentiable number
791 */
792 static const unsigned int n_supported_derivative_levels;
793
794 # else
795
796 /**
797 * A flag to indicate whether the number is of
798 * the taped variety or not
799 */
800 static constexpr bool is_taped = internal::ADNumberInfoFromEnum<
801 typename internal::RemoveComplexWrapper<ScalarType>::type,
802 ADNumberTypeCode>::is_taped;
803
804
805 /**
806 * A flag to indicate whether the number is of
807 * the tapeless variety or not
808 */
809 static constexpr bool is_tapeless =
810 !(NumberTraits<ScalarType, ADNumberTypeCode>::is_taped);
811
812
813 /**
814 * A flag to indicate whether the number represents
815 * a real value
816 */
817 static constexpr bool is_real_valued =
818 (!boost::is_complex<ScalarType>::value);
819
820
821 /**
822 * A flag to indicate whether the number represents
823 * a complex value
824 */
825 static constexpr bool is_complex_valued =
826 !(NumberTraits<ScalarType, ADNumberTypeCode>::is_real_valued);
827
828
829 /**
830 * The number of directional derivatives that can be
831 * taken with this auto-differentiable number
832 */
833 static constexpr unsigned int n_supported_derivative_levels =
834 internal::ADNumberInfoFromEnum<
835 typename internal::RemoveComplexWrapper<ScalarType>::type,
836 ADNumberTypeCode>::n_supported_derivative_levels;
837
838 # endif
839
840
841 /**
842 * Underlying floating point value type.
843 * This could real-valued or complex-valued.
844 */
845 using scalar_type = ScalarType;
846
847
848 /**
849 * Type for real numbers
850 */
851 using real_type = typename internal::ADNumberInfoFromEnum<
852 typename internal::RemoveComplexWrapper<ScalarType>::type,
853 ADNumberTypeCode>::real_type;
854
855
856 /**
857 * Type for complex numbers
858 */
859 using complex_type = std::complex<real_type>;
860
861
862 /**
863 * The actual auto-differentiable number type
864 */
865 using ad_type =
866 typename std::conditional_t<is_real_valued, real_type, complex_type>;
867
868 /**
869 * The actual auto-differentiable number directional derivative type
870 */
871 using derivative_type = std::conditional_t<
872 is_real_valued,
873 typename internal::ADNumberInfoFromEnum<
874 typename internal::RemoveComplexWrapper<ScalarType>::type,
875 ADNumberTypeCode>::derivative_type,
876 std::complex<typename internal::ADNumberInfoFromEnum<
877 typename internal::RemoveComplexWrapper<ScalarType>::type,
878 ADNumberTypeCode>::derivative_type>>;
879
880
881 /**
882 * Extract the value of an auto-differentiable number
883 */
884 static scalar_type get_scalar_value(const ad_type &x)
885 {
886 // Some tricky conversion cases to consider here:
887 // - Nested AD numbers
888 // - std::complex<double> --> std::complex<float>
889 // e.g. when ScalarType = float and ADNumberTypeCode = adolc_taped
890 // Therefore, we use the internal casting mechanism
891 // provided by the internal::NumberType struct.
892 return internal::NumberType<scalar_type>::value(
893 internal::ExtractData<ad_type>::value(x));
894 }
895
896
897 /**
898 * Extract the derivative value of an auto-differentiable number
899 */
900 static derivative_type get_directional_derivative(
901 const ad_type &x, const unsigned int direction)
902 {
903 return internal::ExtractData<ad_type>::directional_derivative(
904 x, direction);
905 }
906
907
908 /**
909 * Extract the number of directional derivatives value tracked by
910 * an auto-differentiable number
911 */
912 static unsigned int n_directional_derivatives(const ad_type &x)
913 {
914 return internal::ExtractData<ad_type>::n_directional_derivatives(x);
915 }
916
917
918 static_assert((is_real_valued == true ?
919 std::is_same_v<ad_type, real_type> :
920 std::is_same_v<ad_type, complex_type>),
921 "Incorrect template type selected for ad_type");
922
923 static_assert((is_complex_valued == true ?
924 boost::is_complex<scalar_type>::value :
925 true),
926 "Expected a complex float_type");
927
928 static_assert((is_complex_valued == true ?
929 boost::is_complex<ad_type>::value :
930 true),
931 "Expected a complex ad_type");
932 };
933
934 # ifdef __clang__
935
936 template <typename ScalarType, enum NumberTypes ADNumberTypeCode>
937 const bool NumberTraits<
938 ScalarType,
939 ADNumberTypeCode,
940 std::enable_if_t<
941 std::is_floating_point_v<ScalarType> ||
942 (boost::is_complex<ScalarType>::value &&
943 std::is_floating_point_v<typename internal::RemoveComplexWrapper<
944 ScalarType>::type>)>>::is_taped =
945 internal::ADNumberInfoFromEnum<
946 typename internal::RemoveComplexWrapper<ScalarType>::type,
947 ADNumberTypeCode>::is_taped;
948
949
950 template <typename ScalarType, enum NumberTypes ADNumberTypeCode>
951 const bool NumberTraits<
952 ScalarType,
953 ADNumberTypeCode,
954 std::enable_if_t<
955 std::is_floating_point_v<ScalarType> ||
956 (boost::is_complex<ScalarType>::value &&
957 std::is_floating_point_v<typename internal::RemoveComplexWrapper<
958 ScalarType>::type>)>>::is_tapeless =
959 !(NumberTraits<ScalarType, ADNumberTypeCode>::is_taped);
960
961
962 template <typename ScalarType, enum NumberTypes ADNumberTypeCode>
963 const bool NumberTraits<
964 ScalarType,
965 ADNumberTypeCode,
966 std::enable_if_t<
967 std::is_floating_point_v<ScalarType> ||
968 (boost::is_complex<ScalarType>::value &&
969 std::is_floating_point_v<typename internal::RemoveComplexWrapper<
970 ScalarType>::type>)>>::is_real_valued =
971 (!boost::is_complex<ScalarType>::value);
972
973
974 template <typename ScalarType, enum NumberTypes ADNumberTypeCode>
975 const bool NumberTraits<
976 ScalarType,
977 ADNumberTypeCode,
978 std::enable_if_t<
979 std::is_floating_point_v<ScalarType> ||
980 (boost::is_complex<ScalarType>::value &&
981 std::is_floating_point_v<typename internal::RemoveComplexWrapper<
982 ScalarType>::type>)>>::is_complex_valued =
983 !(NumberTraits<ScalarType, ADNumberTypeCode>::is_real_valued);
984
985
986 template <typename ScalarType, enum NumberTypes ADNumberTypeCode>
987 const unsigned int NumberTraits<
988 ScalarType,
989 ADNumberTypeCode,
990 std::enable_if_t<
991 std::is_floating_point_v<ScalarType> ||
992 (boost::is_complex<ScalarType>::value &&
993 std::is_floating_point_v<typename internal::RemoveComplexWrapper<
994 ScalarType>::type>)>>::n_supported_derivative_levels =
995 internal::ADNumberInfoFromEnum<
996 typename internal::RemoveComplexWrapper<ScalarType>::type,
997 ADNumberTypeCode>::n_supported_derivative_levels;
998
999 # else
1000
1001 template <typename ScalarType, enum NumberTypes ADNumberTypeCode>
1002 constexpr bool NumberTraits<
1003 ScalarType,
1004 ADNumberTypeCode,
1005 std::enable_if_t<
1006 std::is_floating_point_v<ScalarType> ||
1007 (boost::is_complex<ScalarType>::value &&
1008 std::is_floating_point_v<typename internal::RemoveComplexWrapper<
1009 ScalarType>::type>)>>::is_taped;
1010
1011
1012 template <typename ScalarType, enum NumberTypes ADNumberTypeCode>
1013 constexpr bool NumberTraits<
1014 ScalarType,
1015 ADNumberTypeCode,
1016 std::enable_if_t<
1017 std::is_floating_point_v<ScalarType> ||
1018 (boost::is_complex<ScalarType>::value &&
1019 std::is_floating_point_v<typename internal::RemoveComplexWrapper<
1020 ScalarType>::type>)>>::is_tapeless;
1021
1022
1023 template <typename ScalarType, enum NumberTypes ADNumberTypeCode>
1024 constexpr bool NumberTraits<
1025 ScalarType,
1026 ADNumberTypeCode,
1027 std::enable_if_t<
1028 std::is_floating_point_v<ScalarType> ||
1029 (boost::is_complex<ScalarType>::value &&
1030 std::is_floating_point_v<typename internal::RemoveComplexWrapper<
1031 ScalarType>::type>)>>::is_real_valued;
1032
1033
1034 template <typename ScalarType, enum NumberTypes ADNumberTypeCode>
1035 constexpr bool NumberTraits<
1036 ScalarType,
1037 ADNumberTypeCode,
1038 std::enable_if_t<
1039 std::is_floating_point_v<ScalarType> ||
1040 (boost::is_complex<ScalarType>::value &&
1041 std::is_floating_point_v<typename internal::RemoveComplexWrapper<
1042 ScalarType>::type>)>>::is_complex_valued;
1043
1044
1045 template <typename ScalarType, enum NumberTypes ADNumberTypeCode>
1046 constexpr unsigned int NumberTraits<
1047 ScalarType,
1048 ADNumberTypeCode,
1049 std::enable_if_t<
1050 std::is_floating_point_v<ScalarType> ||
1051 (boost::is_complex<ScalarType>::value &&
1052 std::is_floating_point_v<typename internal::RemoveComplexWrapper<
1053 ScalarType>::type>)>>::n_supported_derivative_levels;
1054
1055 # endif
1056
1057
1058
1059 /**
1060 * A dummy specialization for floating point numbers. This is necessary to
1061 * deal with the special case of the ADNumberTypeCode that represents a
1062 * floating point number.
1063 *
1064 * This specific version specializes the generic case where the template
1065 * @p ScalarType represents a floating point type, or complex number that
1066 * is templated on a floating point type.
1067 */
1068 template <typename ScalarType>
1069 struct NumberTraits<
1070 ScalarType,
1071 NumberTypes::none,
1072 std::enable_if_t<
1073 std::is_floating_point_v<ScalarType> ||
1074 (boost::is_complex<ScalarType>::value &&
1075 std::is_floating_point_v<
1076 typename internal::RemoveComplexWrapper<ScalarType>::type>)>>
1077 {
1078 /**
1079 * The internal number type code.
1080 */
1081 static constexpr enum NumberTypes type_code = NumberTypes::none;
1082
1083 // The clang compiler does not seem to like these
1084 // variables being defined as constant expressions
1085 // (the tests <adolc|sacado>/ad_number_traits_02 will
1086 // fail with linking errors). However, GCC complains
1087 // about the use of non-constant expressions in
1088 // std::conditional.
1089 # ifdef __clang__
1090
1091 /**
1092 * A flag to indicate whether the number is of
1093 * the taped variety or not.
1094 */
1095 static const bool is_taped;
1096
1097
1098 /**
1099 * A flag to indicate whether the number is of
1100 * the tapeless variety or not.
1101 */
1102 static const bool is_tapeless;
1103
1104
1105 /**
1106 * A flag to indicate whether the number represents
1107 * a real value.
1108 */
1109 static const bool is_real_valued;
1110
1111
1112 /**
1113 * A flag to indicate whether the number represents
1114 * a complex value.
1115 */
1116 static const bool is_complex_valued;
1117
1118
1119 /**
1120 * The number of directional derivatives that can be
1121 * taken with this (floating point) number.
1122 */
1123 static const unsigned int n_supported_derivative_levels;
1124
1125 # else
1126
1127 /**
1128 * A flag to indicate whether the number is of
1129 * the taped variety or not.
1130 */
1131 static constexpr bool is_taped = false;
1132
1133
1134 /**
1135 * A flag to indicate whether the number is of
1136 * the tapeless variety or not.
1137 */
1138 static constexpr bool is_tapeless = false;
1139
1140
1141 /**
1142 * A flag to indicate whether the number represents
1143 * a real value.
1144 */
1145 static constexpr bool is_real_valued =
1146 (!boost::is_complex<ScalarType>::value);
1147
1148
1149 /**
1150 * A flag to indicate whether the number represents
1151 * a complex value.
1152 */
1153 static constexpr bool is_complex_valued = !is_real_valued;
1154
1155
1156 /**
1157 * The number of directional derivatives that can be
1158 * taken with this (floating point) number.
1159 */
1160 static constexpr unsigned int n_supported_derivative_levels = 0;
1161
1162 # endif
1163
1164
1165 /**
1166 * Underlying floating point value type.
1167 * This could real-valued or complex-valued.
1168 */
1169 using scalar_type = ScalarType;
1170
1171
1172 /**
1173 * Type for real numbers.
1174 */
1175 using real_type =
1176 typename dealii::numbers::NumberTraits<scalar_type>::real_type;
1177
1178
1179 /**
1180 * Type for complex numbers.
1181 */
1182 using complex_type = std::complex<real_type>;
1183
1184
1185 /**
1186 * The actual auto-differentiable number type.
1187 */
1188 using ad_type = ScalarType;
1189
1190 /**
1191 * The actual auto-differentiable number directional derivative type.
1192 */
1193 using derivative_type = ScalarType;
1194
1195
1196 /**
1197 * Extract the value of an auto-differentiable number.
1198 */
1199 static scalar_type
1200 get_scalar_value(const ad_type &x)
1201 {
1202 return x;
1203 }
1204
1205
1206 /**
1207 * Extract the derivative value of an auto-differentiable number.
1208 */
1209 static derivative_type
1210 get_directional_derivative(const ad_type &, const unsigned int)
1211 {
1212 Assert(
1213 false,
1214 ExcMessage(
1215 "Floating point/arithmetic numbers have no directional derivatives."));
1216 return derivative_type();
1217 }
1218
1219
1220 /**
1221 * Extract the number of directional derivatives value tracked by
1222 * an auto-differentiable number.
1223 */
1224 static unsigned int
1225 n_directional_derivatives(const ad_type &)
1226 {
1227 Assert(
1228 false,
1229 ExcMessage(
1230 "Floating point/arithmetic numbers have no directional derivatives."));
1231 return 0;
1232 }
1233 };
1234
1235 # ifdef __clang__
1236
1237 template <typename ScalarType>
1238 const bool NumberTraits<
1239 ScalarType,
1240 NumberTypes::none,
1241 std::enable_if_t<
1242 std::is_floating_point_v<ScalarType> ||
1243 (boost::is_complex<ScalarType>::value &&
1244 std::is_floating_point_v<typename internal::RemoveComplexWrapper<
1245 ScalarType>::type>)>>::is_taped = false;
1246
1247
1248 template <typename ScalarType>
1249 const bool NumberTraits<
1250 ScalarType,
1251 NumberTypes::none,
1252 std::enable_if_t<
1253 std::is_floating_point_v<ScalarType> ||
1254 (boost::is_complex<ScalarType>::value &&
1255 std::is_floating_point_v<typename internal::RemoveComplexWrapper<
1256 ScalarType>::type>)>>::is_tapeless = false;
1257
1258
1259 template <typename ScalarType>
1260 const bool NumberTraits<
1261 ScalarType,
1262 NumberTypes::none,
1263 std::enable_if_t<
1264 std::is_floating_point_v<ScalarType> ||
1265 (boost::is_complex<ScalarType>::value &&
1266 std::is_floating_point_v<typename internal::RemoveComplexWrapper<
1267 ScalarType>::type>)>>::is_real_valued =
1268 (!boost::is_complex<ScalarType>::value);
1269
1270
1271 template <typename ScalarType>
1272 const bool NumberTraits<
1273 ScalarType,
1274 NumberTypes::none,
1275 std::enable_if_t<
1276 std::is_floating_point_v<ScalarType> ||
1277 (boost::is_complex<ScalarType>::value &&
1278 std::is_floating_point_v<typename internal::RemoveComplexWrapper<
1279 ScalarType>::type>)>>::is_complex_valued =
1280 !(NumberTraits<ScalarType, NumberTypes::none>::is_real_valued);
1281
1282
1283 template <typename ScalarType>
1284 const unsigned int NumberTraits<
1285 ScalarType,
1286 NumberTypes::none,
1287 std::enable_if_t<
1288 std::is_floating_point_v<ScalarType> ||
1289 (boost::is_complex<ScalarType>::value &&
1290 std::is_floating_point_v<typename internal::RemoveComplexWrapper<
1291 ScalarType>::type>)>>::n_supported_derivative_levels = 0;
1292
1293 # else
1294
1295 template <typename ScalarType>
1296 constexpr bool NumberTraits<
1297 ScalarType,
1298 NumberTypes::none,
1299 std::enable_if_t<
1300 std::is_floating_point_v<ScalarType> ||
1301 (boost::is_complex<ScalarType>::value &&
1302 std::is_floating_point_v<typename internal::RemoveComplexWrapper<
1303 ScalarType>::type>)>>::is_taped;
1304
1305
1306 template <typename ScalarType>
1307 constexpr bool NumberTraits<
1308 ScalarType,
1309 NumberTypes::none,
1310 std::enable_if_t<
1311 std::is_floating_point_v<ScalarType> ||
1312 (boost::is_complex<ScalarType>::value &&
1313 std::is_floating_point_v<typename internal::RemoveComplexWrapper<
1314 ScalarType>::type>)>>::is_tapeless;
1315
1316
1317 template <typename ScalarType>
1318 constexpr bool NumberTraits<
1319 ScalarType,
1320 NumberTypes::none,
1321 std::enable_if_t<
1322 std::is_floating_point_v<ScalarType> ||
1323 (boost::is_complex<ScalarType>::value &&
1324 std::is_floating_point_v<typename internal::RemoveComplexWrapper<
1325 ScalarType>::type>)>>::is_real_valued;
1326
1327
1328 template <typename ScalarType>
1329 constexpr bool NumberTraits<
1330 ScalarType,
1331 NumberTypes::none,
1332 std::enable_if_t<
1333 std::is_floating_point_v<ScalarType> ||
1334 (boost::is_complex<ScalarType>::value &&
1335 std::is_floating_point_v<typename internal::RemoveComplexWrapper<
1336 ScalarType>::type>)>>::is_complex_valued;
1337
1338
1339 template <typename ScalarType>
1340 constexpr unsigned int NumberTraits<
1341 ScalarType,
1342 NumberTypes::none,
1343 std::enable_if_t<
1344 std::is_floating_point_v<ScalarType> ||
1345 (boost::is_complex<ScalarType>::value &&
1346 std::is_floating_point_v<typename internal::RemoveComplexWrapper<
1347 ScalarType>::type>)>>::n_supported_derivative_levels;
1348
1349 # endif
1350
1351
1352 /**
1353 * A dummy specialization for floating point numbers.
1354 *
1355 * This is necessary to deal with two situations:
1356 * 1. when the dummy "none" number type is to be used, and
1357 * 2. the tricky case of higher-order derivative extraction from AD numbers.
1358 *
1359 * @note Sacado nests the directional derivatives within Sacado numbers, while
1360 * ADOL-C does not. So, starting off from a scalar function f(x), the number
1361 * type resulting from the computation of a directional derivative f'(x) of
1362 * that function is a floating point number for ADOL-C number types and
1363 * Sacado::FAD<double>, but that of a Sacado::FAD<Sacado::FAD<double>> is a
1364 * Sacado::FAD<double>.
1365 *
1366 * For this reason, when trying to extract higher-order derivatives of a
1367 * number that does not support them the input value to this function may be
1368 * a scalar type.
1369 */
1370 template <typename ScalarType>
1371 struct ADNumberTraits<
1372 ScalarType,
1373 std::enable_if_t<std::is_floating_point_v<ScalarType>>>
1374 : NumberTraits<ScalarType, NumberTypes::none>
1375 {};
1376
1377 /**
1378 * A dummy specialization for complex floating point numbers.
1379 */
1380 template <typename ComplexScalarType>
1381 struct ADNumberTraits<
1382 ComplexScalarType,
1383 std::enable_if_t<
1384 boost::is_complex<ComplexScalarType>::value &&
1385 std::is_floating_point_v<typename ComplexScalarType::value_type>>>
1386 : NumberTraits<ComplexScalarType, NumberTypes::none>
1387 {};
1388
1389 } // namespace AD
1390 } // namespace Differentiation
1391
1392 #endif // DOXYGEN
1393
1394 DEAL_II_NAMESPACE_CLOSE
1395
1396 #endif