Debian Codegraph @

include/deal.II/base/tensor.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 1998 - 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_tensor_h
16 #define dealii_tensor_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/exceptions.h>
21 #include <deal.II/base/kokkos.h>
22 #include <deal.II/base/numbers.h>
23 #include <deal.II/base/table_indices.h>
24 #include <deal.II/base/template_constraints.h>
25 #include <deal.II/base/tensor_accessors.h>
26
27 #include <Kokkos_Array.hpp>
28
29 #ifdef DEAL_II_WITH_ADOLC
30 # include <adolc/adouble.h> // Taped double
31 #endif
32
33 #include <cmath>
34 #include <complex>
35 #include <ostream>
36 #include <type_traits>
37
38 DEAL_II_NAMESPACE_OPEN
39
40 // Forward declarations:
41 #ifndef DOXYGEN
42 template <typename ElementType, typename MemorySpace>
43 class ArrayView;
44
45 template <int dim, typename Number>
46 DEAL_II_CXX20_REQUIRES(dim >= 0)
47 class Point;
48
49 template <int rank_, int dim, typename Number = double>
50 class Tensor;
51 template <typename Number>
52 class Vector;
53 template <typename number>
54 class FullMatrix;
55 namespace Differentiation
56 {
57 namespace SD
58 {
59 class Expression;
60 }
61 } // namespace Differentiation
62 #endif
63
64
65 /**
66 * This class is a specialized version of the <tt>Tensor<rank,dim,Number></tt>
67 * class. It handles tensors of rank zero, i.e. scalars. The second template
68 * argument @p dim is ignored.
69 *
70 * This class exists because in some cases we want to construct objects of
71 * type Tensor@<spacedim-dim,dim,Number@>, which should expand to scalars,
72 * vectors, matrices, etc, depending on the values of the template arguments
73 * @p dim and @p spacedim. We therefore need a class that acts as a scalar
74 * (i.e. @p Number) for all purposes but is part of the Tensor template
75 * family.
76 *
77 * @tparam dim An integer that denotes the dimension of the space in which
78 * this tensor operates. This of course equals the number of coordinates that
79 * identify a point and rank-1 tensor. Since the current object is a rank-0
80 * tensor (a scalar), this template argument has no meaning for this class.
81 *
82 * @tparam Number The data type in which the tensor elements are to be stored.
83 * This will, in almost all cases, simply be the default @p double, but there
84 * are cases where one may want to store elements in a different (and always
85 * scalar) type. It can be used to base tensors on @p float or @p complex
86 * numbers or any other data type that implements basic arithmetic operations.
87 * Another example would be a type that allows for Automatic Differentiation
88 * (see, for example, the Sacado type used in step-33) and thereby can
89 * generate analytic (spatial) derivatives of a function that takes a tensor
90 * as argument.
91 *
92 * @ingroup geomprimitives
93 */
94 template <int dim, typename Number>
95 class Tensor<0, dim, Number>
96 {
97 public:
98 static_assert(dim >= 0,
99 "Tensors must have a dimension greater than or equal to one.");
100
101 /**
102 * Provide a way to get the dimension of an object without explicit
103 * knowledge of it's data type. Implementation is this way instead of
104 * providing a function <tt>dimension()</tt> because now it is possible to
105 * get the dimension at compile time without the expansion and preevaluation
106 * of an inlined function; the compiler may therefore produce more efficient
107 * code and you may use this value to declare other data types.
108 */
109 static constexpr unsigned int dimension = dim;
110
111 /**
112 * Publish the rank of this tensor to the outside world.
113 */
114 static constexpr unsigned int rank = 0;
115
116 /**
117 * Number of independent components of a tensor of rank 0.
118 */
119 static constexpr unsigned int n_independent_components = 1;
120
121 /**
122 * Declare a type that has holds real-valued numbers with the same precision
123 * as the template argument to this class. For std::complex<number>, this
124 * corresponds to type number, and it is equal to Number for all other
125 * cases. See also the respective field in Vector<Number>.
126 *
127 * This alias is used to represent the return type of norms.
128 */
129 using real_type = typename numbers::NumberTraits<Number>::real_type;
130
131 /**
132 * Type of objects encapsulated by this container and returned by
133 * operator[](). This is a scalar number type for a rank 0 tensor.
134 */
135 using value_type = Number;
136
137 /**
138 * Declare an array type which can be used to initialize an object of this
139 * type statically. In case of a tensor of rank 0 this is just the scalar
140 * number type Number.
141 */
142 using array_type = Number;
143
144 /**
145 * Constructor. Set to zero.
146 *
147 * @note This function can also be used in @ref GlossDevice "device" code.
148 */
149 constexpr DEAL_II_HOST_DEVICE
150 Tensor();
151
152 /**
153 * Constructor from tensors with different underlying scalar type. This
154 * obviously requires that the @p OtherNumber type is convertible to @p
155 * Number.
156 *
157 * @note This function can also be used in @ref GlossDevice "device" code.
158 */
159 template <typename OtherNumber>
160 constexpr DEAL_II_HOST_DEVICE
161 Tensor(const Tensor<0, dim, OtherNumber> &initializer);
162
163 /**
164 * Constructor, where the data is copied from a C-style array.
165 *
166 * @note This function can also be used in @ref GlossDevice "device" code.
167 */
168 template <typename OtherNumber>
169 constexpr DEAL_II_HOST_DEVICE
170 Tensor(const OtherNumber &initializer);
171
172 #ifdef DEAL_II_DELETED_MOVE_CONSTRUCTOR_BUG
173 /**
174 * Copy constructor
175 */
176 constexpr DEAL_II_HOST_DEVICE
177 Tensor(const Tensor<0, dim, Number> &other);
178
179 /**
180 * Move constructor
181 */
182 constexpr DEAL_II_HOST_DEVICE
183 Tensor(Tensor<0, dim, Number> &&other) noexcept;
184 #endif
185
186 /**
187 * Return a reference to the encapsulated Number object. Since rank-0
188 * tensors are scalars, this is a natural operation.
189 *
190 * This is the non-const conversion operator that returns a writable
191 * reference.
192 *
193 * @note This function can also be used in @ref GlossDevice "device" code.
194 */
195 constexpr DEAL_II_HOST_DEVICE
196 operator Number &();
197
198 /**
199 * Return a reference to the encapsulated Number object. Since rank-0
200 * tensors are scalars, this is a natural operation.
201 *
202 * This is the const conversion operator that returns a read-only reference.
203 *
204 * @note This function can also be used in @ref GlossDevice "device" code.
205 */
206 constexpr DEAL_II_HOST_DEVICE operator const Number &() const;
207
208 /**
209 * Assignment from tensors with different underlying scalar type. This
210 * obviously requires that the @p OtherNumber type is convertible to @p
211 * Number.
212 *
213 * @note This function can also be used in @ref GlossDevice "device" code.
214 */
215 template <typename OtherNumber>
216 constexpr DEAL_II_HOST_DEVICE Tensor &
217 operator=(const Tensor<0, dim, OtherNumber> &rhs);
218
219 #if defined(__INTEL_COMPILER) || defined(DEAL_II_DELETED_MOVE_CONSTRUCTOR_BUG)
220 /**
221 * Assignment from tensors with same underlying scalar type.
222 * This is needed for ICC15 because it can't generate a suitable
223 * copy constructor for Sacado::Rad::ADvar types automatically.
224 * See https://github.com/dealii/dealii/pull/5865.
225 *
226 * @note This function can also be used in @ref GlossDevice "device" code.
227 */
228 constexpr DEAL_II_HOST_DEVICE Tensor &
229 operator=(const Tensor<0, dim, Number> &rhs);
230 #endif
231
232 #ifdef DEAL_II_DELETED_MOVE_CONSTRUCTOR_BUG
233 /**
234 * Move assignment operator
235 */
236 constexpr DEAL_II_HOST_DEVICE Tensor<0, dim, Number> &
237 operator=(Tensor<0, dim, Number> &&other) noexcept;
238 #endif
239
240 /**
241 * This operator assigns a scalar to a tensor. This obviously requires
242 * that the @p OtherNumber type is convertible to @p Number.
243 *
244 * @note This function can also be used in @ref GlossDevice "device" code.
245 */
246 template <typename OtherNumber>
247 constexpr DEAL_II_HOST_DEVICE Tensor &
248 operator=(const OtherNumber &d) &;
249
250 /**
251 * Assign a scalar to the current object. This overload is used for
252 * rvalue references; because it does not make sense to assign
253 * something to a temporary, the function is deleted.
254 */
255 template <typename OtherNumber>
256 constexpr DEAL_II_HOST_DEVICE Tensor &
257 operator=(const OtherNumber &d) && = delete;
258
259 /**
260 * Test for equality of two tensors.
261 */
262 template <typename OtherNumber>
263 constexpr bool
264 operator==(const Tensor<0, dim, OtherNumber> &rhs) const;
265
266 /**
267 * Test for inequality of two tensors.
268 */
269 template <typename OtherNumber>
270 constexpr bool
271 operator!=(const Tensor<0, dim, OtherNumber> &rhs) const;
272
273 /**
274 * Add another scalar.
275 *
276 * @note This function can also be used in @ref GlossDevice "device" code.
277 */
278 template <typename OtherNumber>
279 constexpr DEAL_II_HOST_DEVICE Tensor &
280 operator+=(const Tensor<0, dim, OtherNumber> &rhs);
281
282 /**
283 * Subtract another scalar.
284 *
285 * @note This function can also be used in @ref GlossDevice "device" code.
286 */
287 template <typename OtherNumber>
288 constexpr DEAL_II_HOST_DEVICE Tensor &
289 operator-=(const Tensor<0, dim, OtherNumber> &rhs);
290
291 /**
292 * Multiply the scalar with a <tt>factor</tt>.
293 *
294 * @note This function can also be used in @ref GlossDevice "device" code.
295 */
296 template <typename OtherNumber>
297 constexpr DEAL_II_HOST_DEVICE Tensor &
298 operator*=(const OtherNumber &factor);
299
300 /**
301 * Divide the scalar by <tt>factor</tt>.
302 *
303 * @note This function can also be used in @ref GlossDevice "device" code.
304 */
305 template <typename OtherNumber>
306 constexpr DEAL_II_HOST_DEVICE Tensor &
307 operator/=(const OtherNumber &factor);
308
309 /**
310 * Tensor with inverted entries.
311 *
312 * @note This function can also be used in @ref GlossDevice "device" code.
313 */
314 constexpr DEAL_II_HOST_DEVICE Tensor
315 operator-() const;
316
317 /**
318 * Reset all values to zero.
319 *
320 * Note that this is partly inconsistent with the semantics of the @p
321 * clear() member functions of the standard library containers and of
322 * several other classes within deal.II, which not only reset the values of
323 * stored elements to zero, but release all memory and return the object
324 * into an empty state. However, since the size of objects of the present
325 * type is determined by its template parameters, resizing is not an option,
326 * and indeed the state where all elements have a zero value is the state
327 * right after construction of such an object.
328 */
329 constexpr void
330 clear();
331
332 /**
333 * Return the Frobenius-norm of a tensor, i.e. the square root of the sum of
334 * the absolute squares of all entries. For the present case of rank-1
335 * tensors, this equals the usual <tt>l<sub>2</sub></tt> norm of the vector.
336 */
337 real_type
338 norm() const;
339
340 /**
341 * Return the square of the Frobenius-norm of a tensor, i.e. the sum of the
342 * absolute squares of all entries.
343 *
344 * @note This function can also be used in @ref GlossDevice "device" code.
345 */
346 constexpr DEAL_II_HOST_DEVICE real_type
347 norm_square() const;
348
349 /**
350 * Fill a range with all tensor elements. Since this type of Tensor only has
351 * one entry this just copies the value of this tensor into <tt>*begin</tt>.
352 *
353 * The template type Number must be convertible to the type of
354 * <tt>*begin</tt>.
355 */
356 template <class Iterator>
357 void
358 unroll(const Iterator begin, const Iterator end) const;
359
360 /**
361 * Read or write the data of this object to or from a stream for the purpose
362 * of serialization using the [BOOST serialization
363 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
364 */
365 template <class Archive>
366 void
367 serialize(Archive &ar, const unsigned int version);
368
369 /**
370 * Internal type declaration that is used to specialize the return type of
371 * operator[]() for Tensor<1,dim,Number>
372 */
373 using tensor_type = Number;
374
375 private:
376 /**
377 * The value of this scalar object.
378 */
379 Number value;
380
381 // Allow an arbitrary Tensor to access the underlying values.
382 template <int, int, typename>
383 friend class Tensor;
384 };
385
386
387
388 /**
389 * A general tensor class with an arbitrary rank, i.e. with an arbitrary
390 * number of indices. The Tensor class provides an indexing operator and a bit
391 * of infrastructure, but most functionality is recursively handed down to
392 * tensors of rank 1 or put into external templated functions, e.g. the
393 * <tt>contract</tt> family.
394 *
395 * The rank of a tensor specifies which types of physical quantities it can
396 * represent:
397 * <ul>
398 * <li> A rank-0 tensor is a scalar that can store quantities such as
399 * temperature or pressure. These scalar quantities are shown in this
400 * documentation as simple lower-case Latin letters e.g. $a, b, c, \dots$.
401 * </li>
402 * <li> A rank-1 tensor is a vector with @p dim components and it can
403 * represent vector quantities such as velocity, displacement, electric
404 * field, etc. They can also describe the gradient of a scalar field.
405 * The notation used for rank-1 tensors is bold-faced lower-case Latin
406 * letters e.g. $\mathbf a, \mathbf b, \mathbf c, \dots$.
407 * The components of a rank-1 tensor such as $\mathbf a$ are represented
408 * as $a_i$ where $i$ is an index between 0 and <tt>dim-1</tt>.
409 * </li>
410 * <li> A rank-2 tensor is a linear operator that can transform a vector
411 * into another vector. These tensors are similar to matrices with
412 * $\text{dim} \times \text{dim}$ components. There is a related class
413 * SymmetricTensor<2,dim> for tensors of rank 2 whose elements are
414 * symmetric. Rank-2 tensors are usually denoted by bold-faced upper-case
415 * Latin letters such as $\mathbf A, \mathbf B, \dots$ or bold-faced Greek
416 * letters for example $\boldsymbol{\varepsilon}, \boldsymbol{\sigma}$.
417 * The components of a rank 2 tensor such as $\mathbf A$ are shown with
418 * two indices $(i,j)$ as $A_{ij}$. These tensors usually describe the
419 * gradients of vector fields (deformation gradient, velocity gradient,
420 * etc.) or Hessians of scalar fields. Additionally, mechanical stress
421 * tensors are rank-2 tensors that map the unit normal vectors of internal
422 * surfaces into local traction (force per unit area) vectors.
423 * </li>
424 * <li> Tensors with ranks higher than 2 are similarly defined in a
425 * consistent manner. They have $\text{dim}^{\text{rank}}$ components and
426 * the number of indices required to identify a component equals
427 * <tt>rank</tt>. For rank-4 tensors, a symmetric variant called
428 * SymmetricTensor<4,dim> exists.
429 * </li>
430 * </ul>
431 *
432 * Using this tensor class for objects of rank 2 has advantages over matrices
433 * in many cases since the dimension is known to the compiler as well as the
434 * location of the data. It is therefore possible to produce far more
435 * efficient code than for matrices with runtime-dependent dimension. It also
436 * makes the code easier to read because of the semantic difference between a
437 * tensor (an object that relates to a coordinate system and has
438 * transformation properties with regard to coordinate rotations and
439 * transforms) and matrices (which we consider as operators on arbitrary
440 * vector spaces related to linear algebra things).
441 *
442 * @tparam rank_ An integer that denotes the rank of this tensor. A
443 * specialization of this class exists for rank-0 tensors.
444 *
445 * @tparam dim An integer that denotes the dimension of the space in which
446 * this tensor operates. This of course equals the number of coordinates that
447 * identify a point and rank-1 tensor.
448 *
449 * @tparam Number The data type in which the tensor elements are to be stored.
450 * This will, in almost all cases, simply be the default @p double, but there
451 * are cases where one may want to store elements in a different (and always
452 * scalar) type. It can be used to base tensors on @p float or @p complex
453 * numbers or any other data type that implements basic arithmetic operations.
454 * Another example would be a type that allows for Automatic Differentiation
455 * (see, for example, the Sacado type used in step-33) and thereby can
456 * generate analytic (spatial) derivatives of a function that takes a tensor
457 * as argument.
458 *
459 * @ingroup geomprimitives
460 */
461 template <int rank_, int dim, typename Number>
462 class Tensor
463 {
464 public:
465 static_assert(rank_ >= 1,
466 "Tensors must have a rank greater than or equal to one.");
467 static_assert(dim >= 0,
468 "Tensors must have a dimension greater than or equal to zero.");
469 /**
470 * Provide a way to get the dimension of an object without explicit
471 * knowledge of it's data type. Implementation is this way instead of
472 * providing a function <tt>dimension()</tt> because now it is possible to
473 * get the dimension at compile time without the expansion and preevaluation
474 * of an inlined function; the compiler may therefore produce more efficient
475 * code and you may use this value to declare other data types.
476 */
477 static constexpr unsigned int dimension = dim;
478
479 /**
480 * Publish the rank of this tensor to the outside world.
481 */
482 static constexpr unsigned int rank = rank_;
483
484 /**
485 * Number of independent components of a tensor of current rank. This is dim
486 * times the number of independent components of each sub-tensor, which
487 * equates to `dim^rank`.
488 *
489 * This number can be used to loop over all of the entries of a tensor,
490 * using the unrolled_to_component_indices() function:
491 * @code
492 * // Fill a tensor of arbitrary rank with ones:
493 * Tensor<rank,dim> t;
494 * for (unsigned int i=0; i<Tensor<rank,dim>::n_independent_components; ++i)
495 * t[Tensor<rank,dim>::unrolled_to_component_indices(i)] = 1.0;
496 * @endcode
497 */
498 static constexpr unsigned int n_independent_components =
499 Tensor<rank_ - 1, dim>::n_independent_components * dim;
500
501 /**
502 * Type of objects encapsulated by this container and returned by
503 * operator[](). This is a tensor of lower rank for a general tensor, and a
504 * scalar number type for rank-1 tensors.
505 */
506 using value_type =
507 std::conditional_t<rank_ == 1, Number, Tensor<rank_ - 1, dim, Number>>;
508
509 /**
510 * Declare an array type which can be used to initialize an object of this
511 * type statically. For rank-1 tensors, this array is simply an array of
512 * length `dim` of scalars of type `Number`. For higher-rank tensors, it is an
513 * array of length `dim` of the `array_type` of the next lower-rank tensor.
514 *
515 * This class is occasionally instantiated for `dim == 0`. C++ does not allow
516 * the creation of zero-length arrays. As a consequence, if `dim==0`, then all
517 * arrays that *should* have length `dim` are instead declared as having
518 * length 1 to avoid compiler errors.
519 */
520 using array_type = std::conditional_t<
521 rank_ == 1,
522 Number[(dim != 0) ? dim : 1],
523 typename Tensor<rank_ - 1, dim, Number>::array_type[(dim != 0) ? dim : 1]>;
524
525 /**
526 * Constructor. Initialize all entries to zero.
527 *
528 * @note This function can also be used in @ref GlossDevice "device" code.
529 */
530 constexpr DEAL_II_HOST_DEVICE_ALWAYS_INLINE
531 Tensor();
532
533 /**
534 * A constructor where the data is copied from a C-style array.
535 *
536 * @note This function can also be used in @ref GlossDevice "device" code.
537 */
538 constexpr DEAL_II_HOST_DEVICE explicit Tensor(const array_type &initializer);
539
540 /**
541 * A constructor where the data is copied from an ArrayView object.
542 * Obviously, the ArrayView object must represent a stretch of
543 * data of size `dim`<sup>`rank`</sup>. The sequentially ordered elements
544 * of the argument `initializer` are interpreted as described by
545 * unrolled_to_component_indices().
546 *
547 * This constructor obviously requires that the @p ElementType type is
548 * either equal to @p Number, or is convertible to @p Number.
549 *
550 * @note This function can also be used in @ref GlossDevice "device" code.
551 */
552 template <typename ElementType, typename MemorySpace>
553 constexpr DEAL_II_HOST_DEVICE explicit Tensor(
554 const ArrayView<ElementType, MemorySpace> &initializer);
555
556 /**
557 * Constructor from tensors with different underlying scalar type. This
558 * obviously requires that the @p OtherNumber type is convertible to @p
559 * Number.
560 *
561 * @note This function can also be used in @ref GlossDevice "device" code.
562 */
563 template <typename OtherNumber>
564 constexpr DEAL_II_HOST_DEVICE
565 Tensor(const Tensor<rank_, dim, OtherNumber> &initializer);
566
567 /**
568 * Constructor that converts from a "tensor of tensors".
569 */
570 template <typename OtherNumber>
571 constexpr Tensor(
572 const Tensor<1, dim, Tensor<rank_ - 1, dim, OtherNumber>> &initializer);
573
574 /**
575 * Conversion operator to tensor of tensors.
576 */
577 template <typename OtherNumber>
578 constexpr
579 operator Tensor<1, dim, Tensor<rank_ - 1, dim, OtherNumber>>() const;
580
581 #ifdef DEAL_II_DELETED_MOVE_CONSTRUCTOR_BUG
582 /**
583 * Copy constructor
584 */
585 constexpr Tensor(const Tensor<rank_, dim, Number> &);
586
587 /**
588 * Move constructor
589 */
590 constexpr Tensor(Tensor<rank_, dim, Number> &&) noexcept;
591 #endif
592
593 /**
594 * Read-Write access operator.
595 *
596 * @note This function can also be used in @ref GlossDevice "device" code.
597 */
598 constexpr DEAL_II_HOST_DEVICE value_type &
599 operator[](const unsigned int i);
600
601 /**
602 * Read-only access operator.
603 *
604 * @note This function can also be used in @ref GlossDevice "device" code.
605 */
606 constexpr DEAL_II_HOST_DEVICE const value_type &
607 operator[](const unsigned int i) const;
608
609 /**
610 * Read access using TableIndices <tt>indices</tt>
611 */
612 constexpr const Number &
613 operator[](const TableIndices<rank_> &indices) const;
614
615 /**
616 * Read and write access using TableIndices <tt>indices</tt>
617 */
618 constexpr Number &
619 operator[](const TableIndices<rank_> &indices);
620
621 /**
622 * Return a pointer to the first element of the underlying storage.
623 */
624 DEAL_II_DEPRECATED
625 Number *
626 begin_raw();
627
628 /**
629 * Return a const pointer to the first element of the underlying storage.
630 */
631 DEAL_II_DEPRECATED
632 const Number *
633 begin_raw() const;
634
635 /**
636 * Return a pointer to the element past the end of the underlying storage.
637 */
638 DEAL_II_DEPRECATED
639 Number *
640 end_raw();
641
642 /**
643 * Return a pointer to the element past the end of the underlying storage.
644 */
645 DEAL_II_DEPRECATED
646 const Number *
647 end_raw() const;
648
649 /**
650 * Assignment operator from tensors with different underlying scalar type.
651 * This obviously requires that the @p OtherNumber type is convertible to @p
652 * Number.
653 *
654 * @note This function can also be used in @ref GlossDevice "device" code.
655 */
656 template <typename OtherNumber>
657 constexpr DEAL_II_HOST_DEVICE Tensor &
658 operator=(const Tensor<rank_, dim, OtherNumber> &rhs);
659
660 /**
661 * This operator assigns a scalar to a tensor. To avoid confusion with what
662 * exactly it means to assign a scalar value to a tensor, zero is the only
663 * value allowed for <tt>d</tt>, allowing the intuitive notation
664 * <tt>t=0</tt> to reset all elements of the tensor to zero.
665 */
666 constexpr DEAL_II_HOST_DEVICE Tensor &
667 operator=(const Number &d) &;
668
669 /**
670 * Assign a scalar to the current object. This overload is used for
671 * rvalue references; because it does not make sense to assign
672 * something to a temporary, the function is deleted.
673 */
674 constexpr DEAL_II_HOST_DEVICE Tensor &
675 operator=(const Number &d) && = delete;
676
677 #ifdef DEAL_II_DELETED_MOVE_CONSTRUCTOR_BUG
678 /**
679 * Copy assignment operator
680 */
681 constexpr Tensor<rank_, dim, Number> &
682 operator=(const Tensor<rank_, dim, Number> &);
683
684 /**
685 * Move assignment operator
686 */
687 constexpr Tensor<rank_, dim, Number> &
688 operator=(Tensor<rank_, dim, Number> &&) noexcept;
689 #endif
690
691 /**
692 * Test for equality of two tensors.
693 */
694 template <typename OtherNumber>
695 constexpr bool
696 operator==(const Tensor<rank_, dim, OtherNumber> &) const;
697
698 /**
699 * Test for inequality of two tensors.
700 */
701 template <typename OtherNumber>
702 constexpr bool
703 operator!=(const Tensor<rank_, dim, OtherNumber> &) const;
704
705 /**
706 * Add another tensor.
707 *
708 * @note This function can also be used in @ref GlossDevice "device" code.
709 */
710 template <typename OtherNumber>
711 constexpr DEAL_II_HOST_DEVICE Tensor &
712 operator+=(const Tensor<rank_, dim, OtherNumber> &);
713
714 /**
715 * Subtract another tensor.
716 *
717 * @note This function can also be used in @ref GlossDevice "device" code.
718 */
719 template <typename OtherNumber>
720 constexpr DEAL_II_HOST_DEVICE Tensor &
721 operator-=(const Tensor<rank_, dim, OtherNumber> &);
722
723 /**
724 * Scale the tensor by <tt>factor</tt>, i.e. multiply all components by
725 * <tt>factor</tt>.
726 *
727 * @note This function can also be used in @ref GlossDevice "device" code.
728 */
729 template <typename OtherNumber>
730 constexpr DEAL_II_HOST_DEVICE Tensor &
731 operator*=(const OtherNumber &factor);
732
733 /**
734 * Scale the vector by <tt>1/factor</tt>.
735 *
736 * @note This function can also be used in @ref GlossDevice "device" code.
737 */
738 template <typename OtherNumber>
739 constexpr DEAL_II_HOST_DEVICE Tensor &
740 operator/=(const OtherNumber &factor);
741
742 /**
743 * Unary minus operator. Negate all entries of a tensor.
744 *
745 * @note This function can also be used in @ref GlossDevice "device" code.
746 */
747 constexpr DEAL_II_HOST_DEVICE Tensor
748 operator-() const;
749
750 /**
751 * Reset all values to zero.
752 *
753 * Note that this is partly inconsistent with the semantics of the @p
754 * clear() member functions of the standard library containers and of
755 * several other classes within deal.II, which not only reset the values of
756 * stored elements to zero, but release all memory and return the object
757 * into an empty state. However, since the size of objects of the present
758 * type is determined by its template parameters, resizing is not an option,
759 * and indeed the state where all elements have a zero value is the state
760 * right after construction of such an object.
761 */
762 constexpr void
763 clear();
764
765 /**
766 * Return the Frobenius-norm of a tensor, i.e. the square root of the sum of
767 * the absolute squares of all entries. For the present case of rank-1
768 * tensors, this equals the usual <tt>l<sub>2</sub></tt> norm of the vector.
769 *
770 * @note This function can also be used in @ref GlossDevice "device" code.
771 */
772 DEAL_II_HOST_DEVICE
773 typename numbers::NumberTraits<Number>::real_type
774 norm() const;
775
776 /**
777 * Return the square of the Frobenius-norm of a tensor, i.e. the sum of the
778 * absolute squares of all entries.
779 *
780 * @note This function can also be used in @ref GlossDevice "device" code.
781 */
782 constexpr DEAL_II_HOST_DEVICE
783 typename numbers::NumberTraits<Number>::real_type
784 norm_square() const;
785
786 /**
787 * Fill a range with all tensor elements.
788 *
789 * This function unrolls all tensor entries into a single, linearly numbered
790 * sequence. The order of the elements is the one given by
791 * component_to_unrolled_index().
792 *
793 * The template type Number must be convertible to the type of
794 * <tt>*begin</tt>.
795 */
796 template <class Iterator>
797 void
798 unroll(const Iterator begin, const Iterator end) const;
799
800 /**
801 * Return an unrolled index in the range $[0,\text{dim}^{\text{rank}}-1]$
802 * for the element of the tensor indexed by the argument to the function.
803 */
804 static constexpr DEAL_II_HOST_DEVICE unsigned int
805 component_to_unrolled_index(const TableIndices<rank_> &indices);
806
807 /**
808 * Opposite of component_to_unrolled_index: For an index in the range
809 * $[0, \text{dim}^{\text{rank}}-1]$, return which set of indices it would
810 * correspond to.
811 */
812 static constexpr DEAL_II_HOST_DEVICE TableIndices<rank_>
813 unrolled_to_component_indices(const unsigned int i);
814
815 /**
816 * Determine an estimate for the memory consumption (in bytes) of this
817 * object.
818 */
819 static constexpr std::size_t
820 memory_consumption();
821
822 /**
823 * Read or write the data of this object to or from a stream for the purpose
824 * of serialization using the [BOOST serialization
825 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
826 */
827 template <class Archive>
828 void
829 serialize(Archive &ar, const unsigned int version);
830
831 /**
832 * Internal type declaration that is used to specialize the return type of
833 * operator[]() for Tensor<1,dim,Number>
834 */
835 using tensor_type = Tensor<rank_, dim, Number>;
836
837 private:
838 /**
839 * Array of tensors holding the elements of the tensor. If this is
840 * a rank-1 tensor, then we simply need an array of scalars.
841 * Otherwise, it is an array of tensors one rank lower.
842 */
843 #if DEAL_II_KOKKOS_VERSION_GTE(3, 7, 0)
844 std::conditional_t<rank_ == 1,
845 Kokkos::Array<Number, dim>,
846 Kokkos::Array<Tensor<rank_ - 1, dim, Number>, dim>>
847 #else
848 std::conditional_t<rank_ == 1,
849 std::array<Number, dim>,
850 std::array<Tensor<rank_ - 1, dim, Number>, dim>>
851 #endif
852 values;
853
854 /**
855 * This constructor is for internal use. It provides a way
856 * to create constexpr constructors for Tensor<rank, dim, Number>
857 *
858 * @note This function can also be used in @ref GlossDevice "device" code.
859 */
860 template <typename ArrayLike, std::size_t... Indices>
861 constexpr DEAL_II_HOST_DEVICE
862 Tensor(const ArrayLike &initializer, std::index_sequence<Indices...>);
863
864 // Allow an arbitrary Tensor to access the underlying values.
865 template <int, int, typename>
866 friend class Tensor;
867
868 // Point is allowed access to the coordinates. This is supposed to improve
869 // speed.
870 friend class Point<dim, Number>;
871 };
872
873
874 #ifndef DOXYGEN
875 namespace internal
876 {
877 // Workaround: The following 4 overloads are necessary to be able to
878 // compile the library with Apple Clang 8 and older. We should remove
879 // these overloads again when we bump the minimal required version to
880 // something later than clang-3.6 / Apple Clang 6.3.
881 template <int rank, int dim, typename T, typename U>
882 struct ProductTypeImpl<Tensor<rank, dim, T>, std::complex<U>>
883 {
884 using type =
885 Tensor<rank, dim, std::complex<typename ProductType<T, U>::type>>;
886 };
887
888 template <int rank, int dim, typename T, typename U>
889 struct ProductTypeImpl<Tensor<rank, dim, std::complex<T>>, std::complex<U>>
890 {
891 using type =
892 Tensor<rank, dim, std::complex<typename ProductType<T, U>::type>>;
893 };
894
895 template <typename T, int rank, int dim, typename U>
896 struct ProductTypeImpl<std::complex<T>, Tensor<rank, dim, U>>
897 {
898 using type =
899 Tensor<rank, dim, std::complex<typename ProductType<T, U>::type>>;
900 };
901
902 template <int rank, int dim, typename T, typename U>
903 struct ProductTypeImpl<std::complex<T>, Tensor<rank, dim, std::complex<U>>>
904 {
905 using type =
906 Tensor<rank, dim, std::complex<typename ProductType<T, U>::type>>;
907 };
908 // end workaround
909
910 /**
911 * The structs below are needed to initialize nested Tensor objects.
912 * Also see numbers.h for another specialization.
913 */
914 template <int rank, int dim, typename T>
915 struct NumberType<Tensor<rank, dim, T>>
916 {
917 static constexpr DEAL_II_HOST_DEVICE_ALWAYS_INLINE const
918 Tensor<rank, dim, T> &
919 value(const Tensor<rank, dim, T> &t)
920 {
921 return t;
922 }
923
924 static constexpr DEAL_II_HOST_DEVICE_ALWAYS_INLINE Tensor<rank, dim, T>
925 value(const T &t)
926 {
927 Tensor<rank, dim, T> tmp;
928 tmp = t;
929 return tmp;
930 }
931 };
932 } // namespace internal
933
934
935 /*---------------------- Inline functions: Tensor<0,dim> ---------------------*/
936
937
938 template <int dim, typename Number>
939 constexpr DEAL_II_HOST_DEVICE_ALWAYS_INLINE
940 Tensor<0, dim, Number>::Tensor()
941 // Some auto-differentiable numbers need explicit
942 // zero initialization such as adtl::adouble.
943 : Tensor{0.0}
944 {}
945
946
947
948 template <int dim, typename Number>
949 template <typename OtherNumber>
950 constexpr DEAL_II_HOST_DEVICE_ALWAYS_INLINE
951 Tensor<0, dim, Number>::Tensor(const OtherNumber &initializer)
952 : value(internal::NumberType<Number>::value(initializer))
953 {}
954
955
956
957 template <int dim, typename Number>
958 template <typename OtherNumber>
959 constexpr DEAL_II_HOST_DEVICE_ALWAYS_INLINE
960 Tensor<0, dim, Number>::Tensor(const Tensor<0, dim, OtherNumber> &p)
961 : Tensor{p.value}
962 {}
963
964
965 # ifdef DEAL_II_DELETED_MOVE_CONSTRUCTOR_BUG
966 template <int dim, typename Number>
967 constexpr DEAL_II_HOST_DEVICE_ALWAYS_INLINE
968 Tensor<0, dim, Number>::Tensor(const Tensor<0, dim, Number> &other)
969 : value{other.value}
970 {}
971
972
973
974 template <int dim, typename Number>
975 constexpr DEAL_II_HOST_DEVICE_ALWAYS_INLINE
976 Tensor<0, dim, Number>::Tensor(Tensor<0, dim, Number> &&other) noexcept
977 : value{std::move(other.value)}
978 {}
979 # endif
980
981
982
983 template <int dim, typename Number>
984 constexpr DEAL_II_HOST_DEVICE_ALWAYS_INLINE
985 Tensor<0, dim, Number>::operator Number &()
986 {
987 Assert(dim != 0,
988 ExcMessage("Cannot access an object of type Tensor<0,0,Number>"));
989 return value;
990 }
991
992
993 template <int dim, typename Number>
994 constexpr inline DEAL_II_ALWAYS_INLINE
995 DEAL_II_HOST_DEVICE Tensor<0, dim, Number>::operator const Number &() const
996 {
997 Assert(dim != 0,
998 ExcMessage("Cannot access an object of type Tensor<0,0,Number>"));
999 return value;
1000 }
1001
1002
1003
1004 template <int dim, typename Number>
1005 template <typename OtherNumber>
1006 constexpr DEAL_II_HOST_DEVICE_ALWAYS_INLINE Tensor<0, dim, Number> &
1007 Tensor<0, dim, Number>::operator=(const Tensor<0, dim, OtherNumber> &p)
1008 {
1009 value = internal::NumberType<Number>::value(p.value);
1010 return *this;
1011 }
1012
1013
1014 # if defined(__INTEL_COMPILER) || defined(DEAL_II_DELETED_MOVE_CONSTRUCTOR_BUG)
1015 template <int dim, typename Number>
1016 constexpr DEAL_II_HOST_DEVICE_ALWAYS_INLINE Tensor<0, dim, Number> &
1017 Tensor<0, dim, Number>::operator=(const Tensor<0, dim, Number> &p)
1018 {
1019 value = p.value;
1020 return *this;
1021 }
1022 # endif
1023
1024 # ifdef DEAL_II_DELETED_MOVE_CONSTRUCTOR_BUG
1025 template <int dim, typename Number>
1026 constexpr DEAL_II_HOST_DEVICE_ALWAYS_INLINE Tensor<0, dim, Number> &
1027 Tensor<0, dim, Number>::operator=(Tensor<0, dim, Number> &&other) noexcept
1028 {
1029 value = std::move(other.value);
1030 return *this;
1031 }
1032 # endif
1033
1034
1035
1036 template <int dim, typename Number>
1037 template <typename OtherNumber>
1038 constexpr DEAL_II_HOST_DEVICE_ALWAYS_INLINE Tensor<0, dim, Number> &
1039 Tensor<0, dim, Number>::operator=(const OtherNumber &d) &
1040 {
1041 value = internal::NumberType<Number>::value(d);
1042 return *this;
1043 }
1044
1045
1046 template <int dim, typename Number>
1047 template <typename OtherNumber>
1048 constexpr inline bool
1049 Tensor<0, dim, Number>::operator==(const Tensor<0, dim, OtherNumber> &p) const
1050 {
1051 # ifdef DEAL_II_ADOLC_WITH_ADVANCED_BRANCHING
1052 Assert(!(std::is_same_v<Number, adouble> ||
1053 std::is_same_v<OtherNumber, adouble>),
1054 ExcMessage(
1055 "The Tensor equality operator for ADOL-C taped numbers has not yet "
1056 "been extended to support advanced branching."));
1057 # endif
1058
1059 return numbers::values_are_equal(value, p.value);
1060 }
1061
1062
1063 template <int dim, typename Number>
1064 template <typename OtherNumber>
1065 constexpr bool
1066 Tensor<0, dim, Number>::operator!=(const Tensor<0, dim, OtherNumber> &p) const
1067 {
1068 return !((*this) == p);
1069 }
1070
1071
1072 template <int dim, typename Number>
1073 template <typename OtherNumber>
1074 constexpr DEAL_II_HOST_DEVICE_ALWAYS_INLINE Tensor<0, dim, Number> &
1075 Tensor<0, dim, Number>::operator+=(const Tensor<0, dim, OtherNumber> &p)
1076 {
1077 value += p.value;
1078 return *this;
1079 }
1080
1081
1082 template <int dim, typename Number>
1083 template <typename OtherNumber>
1084 constexpr DEAL_II_HOST_DEVICE_ALWAYS_INLINE Tensor<0, dim, Number> &
1085 Tensor<0, dim, Number>::operator-=(const Tensor<0, dim, OtherNumber> &p)
1086 {
1087 value -= p.value;
1088 return *this;
1089 }
1090
1091
1092
1093 namespace internal
1094 {
1095 namespace ComplexWorkaround
1096 {
1097 template <typename Number, typename OtherNumber>
1098 constexpr DEAL_II_HOST_DEVICE_ALWAYS_INLINE void
1099 multiply_assign_scalar(Number &val, const OtherNumber &s)
1100 {
1101 val *= s;
1102 }
1103
1104 template <typename Number, typename OtherNumber>
1105 constexpr DEAL_II_HOST_DEVICE_ALWAYS_INLINE void
1106 multiply_assign_scalar(std::complex<Number> &val, const OtherNumber &s)
1107 {
1108 # if DEAL_II_KOKKOS_VERSION_GTE(3, 6, 0)
1109 KOKKOS_IF_ON_HOST((val *= s;))
1110 KOKKOS_IF_ON_DEVICE(({
1111 (void)val;
1112 (void)s;
1113 Kokkos::abort(
1114 "This function is not implemented for std::complex<Number>!\n");
1115 }))
1116 # else
1117 # ifdef KOKKOS_ACTIVE_EXECUTION_MEMORY_SPACE_HOST
1118 val *= s;
1119 # else
1120 (void)val;
1121 (void)s;
1122 Kokkos::abort(
1123 "This function is not implemented for std::complex<Number>!\n");
1124 # endif
1125 # endif
1126 }
1127 } // namespace ComplexWorkaround
1128 } // namespace internal
1129
1130
1131 template <int dim, typename Number>
1132 template <typename OtherNumber>
1133 constexpr DEAL_II_HOST_DEVICE_ALWAYS_INLINE Tensor<0, dim, Number> &
1134 Tensor<0, dim, Number>::operator*=(const OtherNumber &s)
1135 {
1136 internal::ComplexWorkaround::multiply_assign_scalar(value, s);
1137 return *this;
1138 }
1139
1140
1141
1142 template <int dim, typename Number>
1143 template <typename OtherNumber>
1144 constexpr inline DEAL_II_HOST_DEVICE Tensor<0, dim, Number> &
1145 Tensor<0, dim, Number>::operator/=(const OtherNumber &s)
1146 {
1147 value /= s;
1148 return *this;
1149 }
1150
1151
1152 template <int dim, typename Number>
1153 constexpr DEAL_II_HOST_DEVICE_ALWAYS_INLINE Tensor<0, dim, Number>
1154 Tensor<0, dim, Number>::operator-() const
1155 {
1156 return -value;
1157 }
1158
1159
1160 template <int dim, typename Number>
1161 inline DEAL_II_ALWAYS_INLINE typename Tensor<0, dim, Number>::real_type
1162 Tensor<0, dim, Number>::norm() const
1163 {
1164 Assert(dim != 0,
1165 ExcMessage("Cannot access an object of type Tensor<0,0,Number>"));
1166 return numbers::NumberTraits<Number>::abs(value);
1167 }
1168
1169
1170 template <int dim, typename Number>
1171 constexpr DEAL_II_HOST_DEVICE inline DEAL_II_ALWAYS_INLINE
1172 typename Tensor<0, dim, Number>::real_type
1173 Tensor<0, dim, Number>::norm_square() const
1174 {
1175 Assert(dim != 0,
1176 ExcMessage("Cannot access an object of type Tensor<0,0,Number>"));
1177 return numbers::NumberTraits<Number>::abs_square(value);
1178 }
1179
1180
1181
1182 template <int dim, typename Number>
1183 constexpr inline void
1184 Tensor<0, dim, Number>::clear()
1185 {
1186 // Some auto-differentiable numbers need explicit
1187 // zero initialization.
1188 value = internal::NumberType<Number>::value(0.0);
1189 }
1190
1191
1192
1193 template <int dim, typename Number>
1194 template <class Iterator>
1195 inline void
1196 Tensor<0, dim, Number>::unroll(const Iterator begin, const Iterator end) const
1197 {
1198 AssertDimension(std::distance(begin, end), n_independent_components);
1199 Assert(dim != 0,
1200 ExcMessage("Cannot unroll an object of type Tensor<0,0,Number>"));
1201 Assert(std::distance(begin, end) >= 1,
1202 ExcMessage("The provided iterator range must contain at least one "
1203 "element."));
1204 *begin = value;
1205 }
1206
1207
1208
1209 template <int dim, typename Number>
1210 template <class Archive>
1211 inline void
1212 Tensor<0, dim, Number>::serialize(Archive &ar, const unsigned int)
1213 {
1214 ar &value;
1215 }
1216
1217
1218 template <int dim, typename Number>
1219 constexpr unsigned int Tensor<0, dim, Number>::n_independent_components;
1220
1221
1222 /*-------------------- Inline functions: Tensor<rank,dim> --------------------*/
1223
1224 template <int rank_, int dim, typename Number>
1225 template <typename ArrayLike, std::size_t... indices>
1226 constexpr DEAL_II_HOST_DEVICE_ALWAYS_INLINE
1227 Tensor<rank_, dim, Number>::Tensor(const ArrayLike &initializer,
1228 std::index_sequence<indices...>)
1229 // Extract from the 'initializer' a sequence of elements via template
1230 // pack evaluation. This could be as easy as
1231 // values{{ (initializer[indices])... }}
1232 // but of course in practice it is not. The challenge is that if rank>1,
1233 // we want to pass the elements initializer[indices] down to the next
1234 // lower rank tensor for evaluation unchanged. But at the rank==1 level,
1235 // we need to convert to the scalar type 'Number'. This would all be
1236 // relatively straightforward if we could rely on automatic type
1237 // conversion, but for some autodifferentiation types, the conversion
1238 // from the AD to double (i.e., the extraction of a scalar value) is
1239 // not implicit, and we need to call internal::NumberType<Number>::value() --
1240 // but as mentioned, we can only do that for rank==1.
1241 //
1242 // We can achieve all of this by dispatching to a lambda function within
1243 // which we can use a 'if constexpr'.
1244 : values{{([&initializer]() -> value_type {
1245 if constexpr (rank_ == 1)
1246 return internal::NumberType<Number>::value(initializer[indices]);
1247 else
1248 return value_type(initializer[indices]);
1249 }())...}}
1250 {
1251 static_assert(sizeof...(indices) == dim,
1252 "dim should match the number of indices");
1253 }
1254
1255
1256 # if defined(DEAL_II_HAVE_CXX20) && !defined(__NVCC__)
1257
1258 template <int rank_, int dim, typename Number>
1259 constexpr DEAL_II_HOST_DEVICE_ALWAYS_INLINE
1260 Tensor<rank_, dim, Number>::Tensor()
1261 : values(
1262 // In order to initialize the Kokkos::Array<Number,dim>, we would need a
1263 // brace-enclosed list of length 'dim'. There is no way in C++ to create
1264 // such a list in-place, but we can come up with a lambda function that
1265 // expands such a list via template-pack expansion, and then uses this
1266 // list to initialize a Kokkos::Array which it then returns.
1267 //
1268 // The trick to come up with such a lambda function is to have a function
1269 // that takes an argument that depends on a template-pack of integers.
1270 // We will call the function with an integer list of length 'dim', and
1271 // in the function itself expand that pack in a way that it serves as
1272 // a brace-enclosed list of initializers for a Kokkos::Array.
1273 //
1274 // Of course, we do not want to initialize the array with the integers,
1275 // but with zeros. (Or, more correctly, a zero of the element type.)
1276 // The canonical way to do this would be using the comma operator:
1277 // (sequence_element, 0.0)
1278 // returns zero, and
1279 // (sequence, 0.0)...
1280 // returns a list of zeros of the right length. Unfortunately, some
1281 // compilers then warn that the left side of the comma expression has
1282 // no effect -- well, bummer, that was of course exactly the idea.
1283 // We could work around this by using
1284 // (sequence_element * 0.0)
1285 // instead, assuming that the compiler will optimize (known) integer
1286 // times zero to zero, and similarly for (known) integer times times
1287 // default-initialized tensor.
1288 //
1289 // But, instead of relying on compiler optimizations, a better way is
1290 // to simply have another (nested) lambda function that takes the
1291 // integer sequence element as an argument and ignores it, just
1292 // returning a zero instead.
1293 []<std::size_t... I>(
1294 const std::index_sequence<I...> &) constexpr -> decltype(values) {
1295 if constexpr (dim == 0)
1296 {
1297 return {};
1298 }
1299 else if constexpr (rank_ == 1)
1300 {
1301 auto get_zero_and_ignore_argument = [](int) {
1302 return internal::NumberType<Number>::value(0.0);
1303 };
1304 return {{(get_zero_and_ignore_argument(I))...}};
1305 }
1306 else
1307 {
1308 auto get_zero_and_ignore_argument = [](int) {
1309 return Tensor<rank_ - 1, dim, Number>();
1310 };
1311 return {{(get_zero_and_ignore_argument(I))...}};
1312 }
1313 }(std::make_index_sequence<dim>()))
1314 {}
1315
1316 # else
1317
1318 // The C++17 case works in essence the same, except that we can't use a
1319 // lambda function with explicit template parameters, i.e., we can't do
1320 // []<std::size_t... I>(const std::index_sequence<I...> &)
1321 // as above because that's a C++20 feature. Lambda functions in C++17 can
1322 // have template packs as arguments, but we need the ability to *name*
1323 // that template pack (the 'I' above) and that's not possible in C++17.
1324 //
1325 // We work around this by moving the lambda function to a global function
1326 // and using the traditional template syntax on it.
1327 namespace internal
1328 {
1329 namespace TensorInitialization
1330 {
1331 template <int rank, int dim, typename Number, std::size_t... I>
1332 # if DEAL_II_KOKKOS_VERSION_GTE(3, 7, 0)
1333 constexpr Kokkos::Array<typename Tensor<rank, dim, Number>::value_type, dim>
1334 # else
1335 constexpr std::array<typename Tensor<rank, dim, Number>::value_type, dim>
1336 # endif
1337 make_zero_array(const std::index_sequence<I...> &)
1338 {
1339 static_assert(sizeof...(I) == dim, "This is bad.");
1340
1341 // First peel off the case dim==0. If we don't, some compilers
1342 // will warn below that we define these lambda functions but
1343 // never use them (because the expanded list has zero elements,
1344 // and the get_zero_and_ignore_argument() function is not used...)
1345 if constexpr (dim == 0)
1346 {
1347 return {};
1348 }
1349 else if constexpr (rank == 1)
1350 {
1351 auto get_zero_and_ignore_argument = [](int) {
1352 return internal::NumberType<Number>::value(0.0);
1353 };
1354 return {{(get_zero_and_ignore_argument(I))...}};
1355 }
1356 else
1357 {
1358 auto get_zero_and_ignore_argument = [](int) {
1359 return Tensor<rank - 1, dim, Number>();
1360 };
1361 return {{(get_zero_and_ignore_argument(I))...}};
1362 }
1363 }
1364 } // namespace TensorInitialization
1365 } // namespace internal
1366
1367
1368 template <int rank_, int dim, typename Number>
1369 constexpr DEAL_II_HOST_DEVICE_ALWAYS_INLINE
1370 Tensor<rank_, dim, Number>::Tensor()
1371 : values(internal::TensorInitialization::make_zero_array<rank_, dim, Number>(
1372 std::make_index_sequence<dim>()))
1373 {}
1374
1375
1376 # endif
1377
1378
1379 template <int rank_, int dim, typename Number>
1380 constexpr DEAL_II_HOST_DEVICE_ALWAYS_INLINE
1381 Tensor<rank_, dim, Number>::Tensor(const array_type &initializer)
1382 : Tensor(initializer, std::make_index_sequence<dim>{})
1383 {}
1384
1385
1386
1387 template <int rank_, int dim, typename Number>
1388 template <typename ElementType, typename MemorySpace>
1389 constexpr DEAL_II_HOST_DEVICE_ALWAYS_INLINE
1390 Tensor<rank_, dim, Number>::Tensor(
1391 const ArrayView<ElementType, MemorySpace> &initializer)
1392 {
1393 // make nvcc happy
1394 const int my_n_independent_components = n_independent_components;
1395 AssertDimension(initializer.size(), my_n_independent_components);
1396
1397 for (unsigned int i = 0; i < my_n_independent_components; ++i)
1398 (*this)[unrolled_to_component_indices(i)] = initializer[i];
1399 }
1400
1401
1402
1403 template <int rank_, int dim, typename Number>
1404 template <typename OtherNumber>
1405 constexpr DEAL_II_HOST_DEVICE_ALWAYS_INLINE
1406 Tensor<rank_, dim, Number>::Tensor(
1407 const Tensor<rank_, dim, OtherNumber> &initializer)
1408 : Tensor(initializer, std::make_index_sequence<dim>{})
1409 {}
1410
1411
1412
1413 template <int rank_, int dim, typename Number>
1414 template <typename OtherNumber>
1415 constexpr DEAL_II_ALWAYS_INLINE
1416 Tensor<rank_, dim, Number>::Tensor(
1417 const Tensor<1, dim, Tensor<rank_ - 1, dim, OtherNumber>> &initializer)
1418 : Tensor(initializer, std::make_index_sequence<dim>{})
1419 {}
1420
1421
1422
1423 template <int rank_, int dim, typename Number>
1424 template <typename OtherNumber>
1425 constexpr DEAL_II_ALWAYS_INLINE Tensor<rank_, dim, Number>::
1426 operator Tensor<1, dim, Tensor<rank_ - 1, dim, OtherNumber>>() const
1427 {
1428 Tensor<1, dim, Tensor<rank_ - 1, dim, OtherNumber>> x;
1429 std::copy(values.data(), values.data() + values.size(), x.values.data());
1430 return x;
1431 }
1432
1433
1434 # ifdef DEAL_II_DELETED_MOVE_CONSTRUCTOR_BUG
1435 template <int rank_, int dim, typename Number>
1436 constexpr DEAL_II_ALWAYS_INLINE
1437 Tensor<rank_, dim, Number>::Tensor(const Tensor<rank_, dim, Number> &other)
1438 : values(other.values)
1439 {}
1440
1441
1442
1443 template <int rank_, int dim, typename Number>
1444 constexpr DEAL_II_ALWAYS_INLINE
1445 Tensor<rank_, dim, Number>::Tensor(Tensor<rank_, dim, Number> &&other) noexcept
1446 : values(std::move(other.values))
1447 {}
1448 # endif
1449
1450
1451
1452 template <int rank_, int dim, typename Number>
1453 constexpr DEAL_II_HOST_DEVICE_ALWAYS_INLINE
1454 typename Tensor<rank_, dim, Number>::value_type &
1455 Tensor<rank_, dim, Number>::operator[](const unsigned int i)
1456 {
1457 Assert(dim != 0,
1458 ExcMessage("Cannot access an object of type Tensor<rank_,0,Number>"));
1459 AssertIndexRange(i, dim);
1460 DEAL_II_CXX23_ASSUME(i < dim);
1461
1462 return values[i];
1463 }
1464
1465
1466 template <int rank_, int dim, typename Number>
1467 constexpr DEAL_II_ALWAYS_INLINE
1468 DEAL_II_HOST_DEVICE const typename Tensor<rank_, dim, Number>::value_type &
1469 Tensor<rank_, dim, Number>::operator[](const unsigned int i) const
1470 {
1471 Assert(dim != 0,
1472 ExcMessage("Cannot access an object of type Tensor<rank_,0,Number>"));
1473 AssertIndexRange(i, dim);
1474 DEAL_II_CXX23_ASSUME(i < dim);
1475
1476 return values[i];
1477 }
1478
1479
1480 template <int rank_, int dim, typename Number>
1481 constexpr inline DEAL_II_ALWAYS_INLINE const Number &
1482 Tensor<rank_, dim, Number>::operator[](const TableIndices<rank_> &indices) const
1483 {
1484 Assert(dim != 0,
1485 ExcMessage("Cannot access an object of type Tensor<rank_,0,Number>"));
1486
1487 return TensorAccessors::extract<rank_>(*this, indices);
1488 }
1489
1490
1491
1492 template <int rank_, int dim, typename Number>
1493 constexpr inline DEAL_II_ALWAYS_INLINE Number &
1494 Tensor<rank_, dim, Number>::operator[](const TableIndices<rank_> &indices)
1495 {
1496 Assert(dim != 0,
1497 ExcMessage("Cannot access an object of type Tensor<rank_,0,Number>"));
1498
1499 return TensorAccessors::extract<rank_>(*this, indices);
1500 }
1501
1502
1503
1504 template <int rank_, int dim, typename Number>
1505 inline Number *
1506 Tensor<rank_, dim, Number>::begin_raw()
1507 {
1508 static_assert(rank_ == 1,
1509 "This function is only available for rank-1 tensors "
1510 "because higher-rank tensors may not store their elements "
1511 "in a contiguous array.");
1512
1513 return std::addressof(
1514 this->operator[](this->unrolled_to_component_indices(0)));
1515 }
1516
1517
1518
1519 template <int rank_, int dim, typename Number>
1520 inline const Number *
1521 Tensor<rank_, dim, Number>::begin_raw() const
1522 {
1523 static_assert(rank_ == 1,
1524 "This function is only available for rank-1 tensors "
1525 "because higher-rank tensors may not store their elements "
1526 "in a contiguous array.");
1527
1528 return std::addressof(
1529 this->operator[](this->unrolled_to_component_indices(0)));
1530 }
1531
1532
1533
1534 template <int rank_, int dim, typename Number>
1535 inline Number *
1536 Tensor<rank_, dim, Number>::end_raw()
1537 {
1538 static_assert(rank_ == 1,
1539 "This function is only available for rank-1 tensors "
1540 "because higher-rank tensors may not store their elements "
1541 "in a contiguous array.");
1542
1543 return begin_raw() + n_independent_components;
1544 }
1545
1546
1547
1548 template <int rank_, int dim, typename Number>
1549 inline const Number *
1550 Tensor<rank_, dim, Number>::end_raw() const
1551 {
1552 static_assert(rank_ == 1,
1553 "This function is only available for rank-1 tensors "
1554 "because higher-rank tensors may not store their elements "
1555 "in a contiguous array.");
1556
1557 return begin_raw() + n_independent_components;
1558 }
1559
1560
1561
1562 template <int rank_, int dim, typename Number>
1563 template <typename OtherNumber>
1564 constexpr inline DEAL_II_ALWAYS_INLINE Tensor<rank_, dim, Number> &
1565 Tensor<rank_, dim, Number>::operator=(const Tensor<rank_, dim, OtherNumber> &t)
1566 {
1567 // The following loop could be written more concisely using std::copy, but
1568 // that function is only constexpr from C++20 on.
1569 for (unsigned int i = 0; i < dim; ++i)
1570 values[i] = t.values[i];
1571 return *this;
1572 }
1573
1574
1575
1576 template <int rank_, int dim, typename Number>
1577 constexpr DEAL_II_HOST_DEVICE inline DEAL_II_ALWAYS_INLINE
1578 Tensor<rank_, dim, Number> &
1579 Tensor<rank_, dim, Number>::operator=(const Number &d) &
1580 {
1581 Assert(numbers::value_is_zero(d), ExcScalarAssignmentOnlyForZeroValue());
1582
1583 for (unsigned int i = 0; i < dim; ++i)
1584 values[i] = internal::NumberType<Number>::value(0.0);
1585 return *this;
1586 }
1587
1588
1589 # ifdef DEAL_II_DELETED_MOVE_CONSTRUCTOR_BUG
1590 template <int rank_, int dim, typename Number>
1591 constexpr DEAL_II_ALWAYS_INLINE Tensor<rank_, dim, Number> &
1592 Tensor<rank_, dim, Number>::operator=(const Tensor<rank_, dim, Number> &other)
1593 {
1594 for (unsigned int i = 0; i < dim; ++i)
1595 values[i] = other.values[i];
1596 return *this;
1597 }
1598
1599
1600
1601 template <int rank_, int dim, typename Number>
1602 constexpr DEAL_II_ALWAYS_INLINE Tensor<rank_, dim, Number> &
1603 Tensor<rank_, dim, Number>::operator=(
1604 Tensor<rank_, dim, Number> &&other) noexcept
1605 {
1606 for (unsigned int i = 0; i < dim; ++i)
1607 values[i] = other.values[i];
1608 return *this;
1609 }
1610 # endif
1611
1612
1613 template <int rank_, int dim, typename Number>
1614 template <typename OtherNumber>
1615 constexpr inline bool
1616 Tensor<rank_, dim, Number>::operator==(
1617 const Tensor<rank_, dim, OtherNumber> &p) const
1618 {
1619 # ifdef DEAL_II_ADOLC_WITH_ADVANCED_BRANCHING
1620 Assert(!(std::is_same_v<Number, adouble> ||
1621 std::is_same_v<OtherNumber, adouble>),
1622 ExcMessage(
1623 "The Tensor equality operator for ADOL-C taped numbers has not yet "
1624 "been extended to support advanced branching."));
1625 # endif
1626
1627 for (unsigned int i = 0; i < dim; ++i)
1628 if (numbers::values_are_not_equal(values[i], p.values[i]))
1629 return false;
1630 return true;
1631 }
1632
1633
1634 // At some places in the library, we have Point<0> for formal reasons
1635 // (e.g., we sometimes have Quadrature<dim-1> for faces, so we have
1636 // Quadrature<0> for dim=1, and then we have Point<0>). To avoid warnings
1637 // in the above function that the loop end check always fails, we
1638 // implement this function here
1639 template <>
1640 template <>
1641 constexpr inline bool
1642 Tensor<1, 0, double>::operator==(const Tensor<1, 0, double> &) const
1643 {
1644 return true;
1645 }
1646
1647
1648 template <int rank_, int dim, typename Number>
1649 template <typename OtherNumber>
1650 constexpr bool
1651 Tensor<rank_, dim, Number>::operator!=(
1652 const Tensor<rank_, dim, OtherNumber> &p) const
1653 {
1654 return !((*this) == p);
1655 }
1656
1657
1658 template <int rank_, int dim, typename Number>
1659 template <typename OtherNumber>
1660 constexpr inline DEAL_II_ALWAYS_INLINE
1661 DEAL_II_HOST_DEVICE Tensor<rank_, dim, Number> &
1662 Tensor<rank_, dim, Number>::operator+=(
1663 const Tensor<rank_, dim, OtherNumber> &p)
1664 {
1665 for (unsigned int i = 0; i < dim; ++i)
1666 values[i] += p.values[i];
1667 return *this;
1668 }
1669
1670
1671 template <int rank_, int dim, typename Number>
1672 template <typename OtherNumber>
1673 constexpr inline DEAL_II_ALWAYS_INLINE
1674 DEAL_II_HOST_DEVICE Tensor<rank_, dim, Number> &
1675 Tensor<rank_, dim, Number>::operator-=(
1676 const Tensor<rank_, dim, OtherNumber> &p)
1677 {
1678 for (unsigned int i = 0; i < dim; ++i)
1679 values[i] -= p.values[i];
1680 return *this;
1681 }
1682
1683
1684 template <int rank_, int dim, typename Number>
1685 template <typename OtherNumber>
1686 constexpr inline DEAL_II_ALWAYS_INLINE
1687 DEAL_II_HOST_DEVICE Tensor<rank_, dim, Number> &
1688 Tensor<rank_, dim, Number>::operator*=(const OtherNumber &s)
1689 {
1690 for (unsigned int i = 0; i < dim; ++i)
1691 values[i] *= s;
1692 return *this;
1693 }
1694
1695
1696
1697 template <int rank_, int dim, typename Number>
1698 template <typename OtherNumber>
1699 constexpr inline DEAL_II_ALWAYS_INLINE
1700 DEAL_II_HOST_DEVICE Tensor<rank_, dim, Number> &
1701 Tensor<rank_, dim, Number>::operator/=(const OtherNumber &s)
1702 {
1703 if constexpr (std::is_integral_v<
1704 typename ProductType<Number, OtherNumber>::type> ||
1705 std::is_same_v<Number, Differentiation::SD::Expression>)
1706 {
1707 // recurse over the base objects
1708 for (unsigned int d = 0; d < dim; ++d)
1709 values[d] /= s;
1710 }
1711 else
1712 {
1713 // If we can, avoid division by multiplying by the inverse of the given
1714 // factor:
1715 const Number inverse_factor = Number(1.) / s;
1716 for (unsigned int d = 0; d < dim; ++d)
1717 values[d] *= inverse_factor;
1718 }
1719
1720 return *this;
1721 }
1722
1723
1724 template <int rank_, int dim, typename Number>
1725 constexpr inline DEAL_II_ALWAYS_INLINE
1726 DEAL_II_HOST_DEVICE Tensor<rank_, dim, Number>
1727 Tensor<rank_, dim, Number>::operator-() const
1728 {
1729 Tensor<rank_, dim, Number> tmp;
1730
1731 for (unsigned int i = 0; i < dim; ++i)
1732 tmp.values[i] = -values[i];
1733
1734 return tmp;
1735 }
1736
1737
1738 template <int rank_, int dim, typename Number>
1739 inline DEAL_II_HOST_DEVICE typename numbers::NumberTraits<Number>::real_type
1740 Tensor<rank_, dim, Number>::norm() const
1741 {
1742 // Handle cases of a tensor consisting of just one number more
1743 // efficiently:
1744 if constexpr ((rank_ == 1) && (dim == 1) && std::is_arithmetic_v<Number>)
1745 {
1746 return std::abs(values[0]);
1747 }
1748 else if constexpr ((rank_ == 2) && (dim == 1) && std::is_arithmetic_v<Number>)
1749 {
1750 return std::abs(values[0][0]);
1751 }
1752 else
1753 {
1754 // Otherwise fall back to the naive algorithm of taking the square root of
1755 // the sum of squares.
1756
1757 // Make things work with AD types by letting the compiler look up
1758 // the symbol sqrt in namespace std and in the type-associated
1759 // namespaces
1760 using std::sqrt;
1761 return sqrt(norm_square());
1762 }
1763 }
1764
1765
1766 template <int rank_, int dim, typename Number>
1767 constexpr DEAL_II_HOST_DEVICE_ALWAYS_INLINE
1768 typename numbers::NumberTraits<Number>::real_type
1769 Tensor<rank_, dim, Number>::norm_square() const
1770 {
1771 if constexpr (dim == 0)
1772 return internal::NumberType<
1773 typename numbers::NumberTraits<Number>::real_type>::value(0.0);
1774 else if constexpr (rank_ == 1)
1775 {
1776 // For rank-1 tensors, the square of the norm is simply the sum of
1777 // squares of the elements:
1778 typename numbers::NumberTraits<Number>::real_type s =
1779 numbers::NumberTraits<Number>::abs_square(values[0]);
1780 for (unsigned int i = 1; i < dim; ++i)
1781 s += numbers::NumberTraits<Number>::abs_square(values[i]);
1782
1783 return s;
1784 }
1785 else
1786 {
1787 // For higher-rank tensors, the square of the norm is the sum
1788 // of squares of sub-tensors
1789 typename numbers::NumberTraits<Number>::real_type s =
1790 values[0].norm_square();
1791 for (unsigned int i = 1; i < dim; ++i)
1792 s += values[i].norm_square();
1793
1794 return s;
1795 }
1796 }
1797
1798
1799
1800 template <int rank_, int dim, typename Number>
1801 template <class Iterator>
1802 inline void
1803 Tensor<rank_, dim, Number>::unroll(const Iterator begin,
1804 const Iterator end) const
1805 {
1806 if constexpr (rank_ > 1)
1807 {
1808 // For higher-rank tensors, we recurse to the sub-tensors:
1809 Iterator next = begin;
1810 for (unsigned int i = 0; i < dim; ++i)
1811 {
1812 values[i].unroll(next, end);
1813 std::advance(
1814 next, Tensor<rank_ - 1, dim, Number>::n_independent_components);
1815 }
1816 }
1817 else
1818 {
1819 // For rank-1 tensors, we can simply copy the current elements from
1820 // our linear array into the output range:
1821 Assert(std::distance(begin, end) >= dim,
1822 ExcMessage(
1823 "The provided iterator range must contain at least 'dim' "
1824 "elements."));
1825 std::copy(values.data(), values.data() + values.size(), begin);
1826 }
1827 }
1828
1829
1830
1831 template <int rank_, int dim, typename Number>
1832 constexpr inline unsigned int
1833 Tensor<rank_, dim, Number>::component_to_unrolled_index(
1834 const TableIndices<rank_> &indices)
1835 {
1836 unsigned int index = 0;
1837 for (int r = 0; r < rank_; ++r)
1838 index = index * dim + indices[r];
1839
1840 return index;
1841 }
1842
1843
1844
1845 template <int rank_, int dim, typename Number>
1846 constexpr inline TableIndices<rank_>
1847 Tensor<rank_, dim, Number>::unrolled_to_component_indices(const unsigned int i)
1848 {
1849 // Work-around nvcc warning
1850 unsigned int dummy = n_independent_components;
1851 AssertIndexRange(i, dummy);
1852
1853 if constexpr (dim == 0)
1854 {
1855 Assert(false,
1856 ExcMessage(
1857 "A tensor with dimension 0 does not store any elements. "
1858 "There is no indexing that can address its elements."));
1859 return {};
1860 }
1861 else
1862 {
1863 TableIndices<rank_> indices;
1864
1865 unsigned int remainder = i;
1866 for (int r = rank_ - 1; r >= 0; --r)
1867 {
1868 indices[r] = remainder % dim;
1869 remainder = remainder / dim;
1870 }
1871 Assert(remainder == 0, ExcInternalError());
1872
1873 return indices;
1874 }
1875 }
1876
1877
1878 template <int rank_, int dim, typename Number>
1879 constexpr inline void
1880 Tensor<rank_, dim, Number>::clear()
1881 {
1882 for (unsigned int i = 0; i < dim; ++i)
1883 values[i] = internal::NumberType<Number>::value(0.0);
1884 }
1885
1886
1887 template <int rank_, int dim, typename Number>
1888 constexpr std::size_t
1889 Tensor<rank_, dim, Number>::memory_consumption()
1890 {
1891 return sizeof(Tensor<rank_, dim, Number>);
1892 }
1893
1894
1895 template <int rank_, int dim, typename Number>
1896 template <class Archive>
1897 inline void
1898 Tensor<rank_, dim, Number>::serialize(Archive &ar, const unsigned int)
1899 {
1900 for (int i = 0; i < dim; ++i)
1901 {
1902 ar &values[i];
1903 }
1904 }
1905
1906
1907 template <int rank_, int dim, typename Number>
1908 constexpr unsigned int Tensor<rank_, dim, Number>::n_independent_components;
1909
1910 #endif // DOXYGEN
1911
1912 /* ----------------- Non-member functions operating on tensors. ------------ */
1913
1914 /**
1915 * @name Output functions for Tensor objects
1916 * @{
1917 */
1918
1919 /**
1920 * Output operator for tensors. Print the elements consecutively, with a space
1921 * in between, two spaces between rank 1 subtensors, three between rank 2 and
1922 * so on.
1923 *
1924 * @relatesalso Tensor
1925 */
1926 template <int rank_, int dim, typename Number>
1927 inline std::ostream &
1928 operator<<(std::ostream &out, const Tensor<rank_, dim, Number> &p)
1929 {
1930 for (unsigned int i = 0; i < dim; ++i)
1931 {
1932 out << p[i];
1933 if (i != dim - 1)
1934 for (unsigned int j = 0; j < rank_; ++j)
1935 out << ' ';
1936 }
1937
1938 return out;
1939 }
1940
1941
1942 /**
1943 * Output operator for tensors of rank 0. Since such tensors are scalars, we
1944 * simply print this one value.
1945 *
1946 * @relatesalso Tensor
1947 */
1948 template <int dim, typename Number>
1949 inline std::ostream &
1950 operator<<(std::ostream &out, const Tensor<0, dim, Number> &p)
1951 {
1952 out << static_cast<const Number &>(p);
1953 return out;
1954 }
1955
1956
1957 /**
1958 * @}
1959 */
1960 /**
1961 * @name Vector space operations on Tensor objects
1962 * @{
1963 */
1964
1965 /**
1966 * Scalar multiplication of a tensor of rank 0 with an object from the left.
1967 *
1968 * This function unwraps the underlying @p Number stored in the Tensor and
1969 * multiplies @p object with it.
1970 *
1971 * @note This function can also be used in @ref GlossDevice "device" code.
1972 *
1973 * @relatesalso Tensor
1974 */
1975 template <int dim, typename Number, typename Other>
1976 constexpr DEAL_II_HOST_DEVICE inline DEAL_II_ALWAYS_INLINE
1977 typename ProductType<Other, Number>::type
1978 operator*(const Other &object, const Tensor<0, dim, Number> &t)
1979 {
1980 return object * static_cast<const Number &>(t);
1981 }
1982
1983
1984
1985 /**
1986 * Scalar multiplication of a tensor of rank 0 with an object from the right.
1987 *
1988 * This function unwraps the underlying @p Number stored in the Tensor and
1989 * multiplies @p object with it.
1990 *
1991 * @note This function can also be used in @ref GlossDevice "device" code.
1992 *
1993 * @relatesalso Tensor
1994 */
1995 template <int dim, typename Number, typename Other>
1996 constexpr DEAL_II_HOST_DEVICE inline DEAL_II_ALWAYS_INLINE
1997 typename ProductType<Number, Other>::type
1998 operator*(const Tensor<0, dim, Number> &t, const Other &object)
1999 {
2000 return static_cast<const Number &>(t) * object;
2001 }
2002
2003
2004 /**
2005 * Scalar multiplication of two tensors of rank 0.
2006 *
2007 * This function unwraps the underlying objects of type @p Number and @p
2008 * OtherNumber that are stored within the Tensor and multiplies them. It
2009 * returns an unwrapped number of product type.
2010 *
2011 * @note This function can also be used in @ref GlossDevice "device" code.
2012 *
2013 * @relatesalso Tensor
2014 */
2015 template <int dim, typename Number, typename OtherNumber>
2016 DEAL_II_HOST_DEVICE constexpr DEAL_II_ALWAYS_INLINE
2017 typename ProductType<Number, OtherNumber>::type
2018 operator*(const Tensor<0, dim, Number> &src1,
2019 const Tensor<0, dim, OtherNumber> &src2)
2020 {
2021 return static_cast<const Number &>(src1) *
2022 static_cast<const OtherNumber &>(src2);
2023 }
2024
2025
2026 /**
2027 * Division of a tensor of rank 0 by a scalar number.
2028 *
2029 * @note This function can also be used in @ref GlossDevice "device" code.
2030 *
2031 * @relatesalso Tensor
2032 */
2033 template <int dim, typename Number, typename OtherNumber>
2034 DEAL_II_HOST_DEVICE constexpr DEAL_II_ALWAYS_INLINE
2035 Tensor<0,
2036 dim,
2037 typename ProductType<Number,
2038 typename EnableIfScalar<OtherNumber>::type>::type>
2039 operator/(const Tensor<0, dim, Number> &t, const OtherNumber &factor)
2040 {
2041 return static_cast<const Number &>(t) / factor;
2042 }
2043
2044
2045 /**
2046 * Add two tensors of rank 0.
2047 *
2048 * @note This function can also be used in @ref GlossDevice "device" code.
2049 *
2050 * @relatesalso Tensor
2051 */
2052 template <int dim, typename Number, typename OtherNumber>
2053 constexpr DEAL_II_HOST_DEVICE_ALWAYS_INLINE
2054 Tensor<0, dim, typename ProductType<Number, OtherNumber>::type>
2055 operator+(const Tensor<0, dim, Number> &p,
2056 const Tensor<0, dim, OtherNumber> &q)
2057 {
2058 return static_cast<const Number &>(p) + static_cast<const OtherNumber &>(q);
2059 }
2060
2061
2062 /**
2063 * Subtract two tensors of rank 0.
2064 *
2065 * @note This function can also be used in @ref GlossDevice "device" code.
2066 *
2067 * @relatesalso Tensor
2068 */
2069 template <int dim, typename Number, typename OtherNumber>
2070 constexpr DEAL_II_HOST_DEVICE_ALWAYS_INLINE
2071 Tensor<0, dim, typename ProductType<Number, OtherNumber>::type>
2072 operator-(const Tensor<0, dim, Number> &p,
2073 const Tensor<0, dim, OtherNumber> &q)
2074 {
2075 return static_cast<const Number &>(p) - static_cast<const OtherNumber &>(q);
2076 }
2077
2078
2079 /**
2080 * Multiplication of a tensor of general rank with a scalar number from the
2081 * right.
2082 *
2083 * Only multiplication with a scalar number type (i.e., a floating point
2084 * number, a complex floating point number, etc.) is allowed, see the
2085 * documentation of EnableIfScalar for details.
2086 *
2087 * @note This function can also be used in @ref GlossDevice "device" code.
2088 *
2089 * @relatesalso Tensor
2090 */
2091 template <int rank, int dim, typename Number, typename OtherNumber>
2092 constexpr DEAL_II_HOST_DEVICE inline DEAL_II_ALWAYS_INLINE
2093 Tensor<rank,
2094 dim,
2095 typename ProductType<Number,
2096 typename EnableIfScalar<OtherNumber>::type>::type>
2097 operator*(const Tensor<rank, dim, Number> &t, const OtherNumber &factor)
2098 {
2099 Tensor<rank, dim, typename ProductType<Number, OtherNumber>::type> tt(t);
2100 tt *= factor;
2101 return tt;
2102 }
2103
2104
2105 /**
2106 * Multiplication of a tensor of general rank with a scalar number from the
2107 * left.
2108 *
2109 * Only multiplication with a scalar number type (i.e., a floating point
2110 * number, a complex floating point number, etc.) is allowed, see the
2111 * documentation of EnableIfScalar for details.
2112 *
2113 * @note This function can also be used in @ref GlossDevice "device" code.
2114 *
2115 * @relatesalso Tensor
2116 */
2117 template <int rank, int dim, typename Number, typename OtherNumber>
2118 DEAL_II_HOST_DEVICE constexpr inline DEAL_II_ALWAYS_INLINE
2119 Tensor<rank,
2120 dim,
2121 typename ProductType<typename EnableIfScalar<Number>::type,
2122 OtherNumber>::type>
2123 operator*(const Number &factor, const Tensor<rank, dim, OtherNumber> &t)
2124 {
2125 // simply forward to the operator above
2126 return t * factor;
2127 }
2128
2129
2130
2131 /**
2132 * Division of a tensor of general rank with a scalar number. See the
2133 * discussion on operator*() above for more information about template
2134 * arguments and the return type.
2135 *
2136 * @note This function can also be used in @ref GlossDevice "device" code.
2137 *
2138 * @relatesalso Tensor
2139 */
2140 template <int rank, int dim, typename Number, typename OtherNumber>
2141 constexpr DEAL_II_HOST_DEVICE inline DEAL_II_ALWAYS_INLINE
2142 Tensor<rank,
2143 dim,
2144 typename ProductType<Number,
2145 typename EnableIfScalar<OtherNumber>::type>::type>
2146 operator/(const Tensor<rank, dim, Number> &t, const OtherNumber &factor)
2147 {
2148 Tensor<rank, dim, typename ProductType<Number, OtherNumber>::type> tt(t);
2149 tt /= factor;
2150 return tt;
2151 }
2152
2153
2154 /**
2155 * Addition of two tensors of general rank.
2156 *
2157 * @tparam rank The rank of both tensors.
2158 *
2159 * @note This function can also be used in @ref GlossDevice "device" code.
2160 *
2161 * @relatesalso Tensor
2162 */
2163 template <int rank, int dim, typename Number, typename OtherNumber>
2164 constexpr DEAL_II_HOST_DEVICE inline DEAL_II_ALWAYS_INLINE
2165 Tensor<rank, dim, typename ProductType<Number, OtherNumber>::type>
2166 operator+(const Tensor<rank, dim, Number> &p,
2167 const Tensor<rank, dim, OtherNumber> &q)
2168 {
2169 Tensor<rank, dim, typename ProductType<Number, OtherNumber>::type> tmp(p);
2170 tmp += q;
2171 return tmp;
2172 }
2173
2174
2175 /**
2176 * Subtraction of two tensors of general rank.
2177 *
2178 * @tparam rank The rank of both tensors.
2179 *
2180 * @note This function can also be used in @ref GlossDevice "device" code.
2181 *
2182 * @relatesalso Tensor
2183 */
2184 template <int rank, int dim, typename Number, typename OtherNumber>
2185 constexpr DEAL_II_HOST_DEVICE inline DEAL_II_ALWAYS_INLINE
2186 Tensor<rank, dim, typename ProductType<Number, OtherNumber>::type>
2187 operator-(const Tensor<rank, dim, Number> &p,
2188 const Tensor<rank, dim, OtherNumber> &q)
2189 {
2190 Tensor<rank, dim, typename ProductType<Number, OtherNumber>::type> tmp(p);
2191 tmp -= q;
2192 return tmp;
2193 }
2194
2195 /**
2196 * Entrywise multiplication of two tensor objects of rank 0 (i.e. the
2197 * multiplication of two scalar values).
2198 *
2199 * @relatesalso Tensor
2200 */
2201 template <int dim, typename Number, typename OtherNumber>
2202 inline constexpr DEAL_II_ALWAYS_INLINE
2203 Tensor<0, dim, typename ProductType<Number, OtherNumber>::type>
2204 schur_product(const Tensor<0, dim, Number> &src1,
2205 const Tensor<0, dim, OtherNumber> &src2)
2206 {
2207 Tensor<0, dim, typename ProductType<Number, OtherNumber>::type> tmp(src1);
2208
2209 tmp *= src2;
2210
2211 return tmp;
2212 }
2213
2214 /**
2215 * Entrywise multiplication of two tensor objects of general rank.
2216 *
2217 * This multiplication is also called "Hadamard-product" (c.f.
2218 * https://en.wikipedia.org/wiki/Hadamard_product_(matrices)), and generates a
2219 * new tensor of size <rank, dim>:
2220 * @f[
2221 * \text{result}_{i, j}
2222 * = \text{left}_{i, j}\circ
2223 * \text{right}_{i, j}
2224 * @f]
2225 *
2226 * @tparam rank The rank of both tensors.
2227 *
2228 * @relatesalso Tensor
2229 */
2230 template <int rank, int dim, typename Number, typename OtherNumber>
2231 inline constexpr DEAL_II_ALWAYS_INLINE
2232 Tensor<rank, dim, typename ProductType<Number, OtherNumber>::type>
2233 schur_product(const Tensor<rank, dim, Number> &src1,
2234 const Tensor<rank, dim, OtherNumber> &src2)
2235 {
2236 Tensor<rank, dim, typename ProductType<Number, OtherNumber>::type> tmp;
2237
2238 for (unsigned int i = 0; i < dim; ++i)
2239 tmp[i] = schur_product(Tensor<rank - 1, dim, Number>(src1[i]),
2240 Tensor<rank - 1, dim, OtherNumber>(src2[i]));
2241
2242 return tmp;
2243 }
2244
2245 /**
2246 * @}
2247 */
2248 /**
2249 * @name Contraction operations and the outer product for tensor objects
2250 * @{
2251 */
2252
2253 /**
2254 * The dot product (single contraction) for tensors. This function return a
2255 * tensor of rank
2256 * $(\text{rank}_1 + \text{rank}_2 - 2)$ that is the contraction of the last
2257 * index of a tensor @p src1 of rank @p rank_1 with the first index of a
2258 * tensor @p src2 of rank @p rank_2:
2259 * @f[
2260 * \text{result}_{i_1,\ldots,i_{r1},j_1,\ldots,j_{r2}}
2261 * = \sum_{k}
2262 * \text{left}_{i_1,\ldots,i_{r1}, k}
2263 * \text{right}_{k, j_1,\ldots,j_{r2}}
2264 * @f]
2265 *
2266 * @note For the Tensor class, the multiplication operator only performs a
2267 * contraction over a single pair of indices. This is in contrast to the
2268 * multiplication operator for SymmetricTensor, for which the corresponding
2269 * `operator*()` performs a double contraction. The origin of the difference in
2270 * how `operator*()` is implemented between Tensor and SymmetricTensor is that
2271 * for the former, the product between two Tensor objects of same rank and
2272 * dimension results in another Tensor object -- that it, `operator*()`
2273 * corresponds to the multiplicative group action within the group of tensors.
2274 * On the other hand, there is no corresponding multiplicative group action with
2275 * the set of symmetric tensors because, in general, the product of two
2276 * symmetric tensors is a *nonsymmetric* tensor. As a consequence, for a
2277 * mathematician, it is clear that `operator*()` for symmetric tensors must have
2278 * a different meaning: namely the *dot* or *scalar product* that maps two
2279 * symmetric tensors of rank 2 to a scalar. This corresponds to the double-dot
2280 * (colon) operator whose meaning is then extended to the product of any two
2281 * even-ranked symmetric tensors.
2282 *
2283 * @note In case the contraction yields a tensor of rank 0, that is, if
2284 * `rank_1==rank_2==1`, then a scalar number is returned as an unwrapped
2285 * number type.
2286 *
2287 * @relatesalso Tensor
2288 */
2289 template <int rank_1,
2290 int rank_2,
2291 int dim,
2292 typename Number,
2293 typename OtherNumber,
2294 typename = std::enable_if_t<rank_1 >= 1 && rank_2 >= 1>>
2295 constexpr inline DEAL_II_ALWAYS_INLINE
2296 typename Tensor<rank_1 + rank_2 - 2,
2297 dim,
2298 typename ProductType<Number, OtherNumber>::type>::tensor_type
2299 operator*(const Tensor<rank_1, dim, Number> &src1,
2300 const Tensor<rank_2, dim, OtherNumber> &src2)
2301 {
2302 // Treat some common cases separately. Specifically, these are the dot
2303 // product between two rank-1 tensors, and the product between a
2304 // rank-2 tensor and a rank-1 tensor. Both of these lead to a linear
2305 // loop over adjacent memory and can be dealt with efficiently; in the
2306 // latter case (rank-2 times rank-1), we implement things by deferring
2307 // to rank-1 times rank-1 dot products.
2308 if constexpr ((rank_1 == 1) && (rank_2 == 1))
2309 {
2310 // This is a dot product between two rank-1 tensors. Write it out as
2311 // a linear loop:
2312 static_assert(dim > 0, "Tensors cannot have dimension zero.");
2313 typename ProductType<Number, OtherNumber>::type sum = src1[0] * src2[0];
2314 for (unsigned int i = 1; i < dim; ++i)
2315 sum += src1[i] * src2[i];
2316
2317 return sum;
2318 }
2319 else if constexpr ((rank_1 == 2) && (rank_2 == 1))
2320 {
2321 // This is a product between a rank-2 and a rank-1 tensor. This
2322 // corresponds to taking dot products between the rows of the former
2323 // and the latter.
2324 typename Tensor<
2325 rank_1 + rank_2 - 2,
2326 dim,
2327 typename ProductType<Number, OtherNumber>::type>::tensor_type result;
2328 for (unsigned int i = 0; i < dim; ++i)
2329 result[i] += src1[i] * src2;
2330
2331 return result;
2332 }
2333 else
2334 {
2335 // Treat all of the other cases using the more general contraction
2336 // machinery.
2337 typename Tensor<
2338 rank_1 + rank_2 - 2,
2339 dim,
2340 typename ProductType<Number, OtherNumber>::type>::tensor_type result{};
2341
2342 TensorAccessors::internal::
2343 ReorderedIndexView<0, rank_2, const Tensor<rank_2, dim, OtherNumber>>
2344 reordered = TensorAccessors::reordered_index_view<0, rank_2>(src2);
2345 TensorAccessors::contract<1, rank_1, rank_2, dim>(result,
2346 src1,
2347 reordered);
2348
2349 return result;
2350 }
2351 }
2352
2353
2354 /**
2355 * Generic contraction of a pair of indices of two tensors of arbitrary rank:
2356 * Return a tensor of rank $(\text{rank}_1 + \text{rank}_2 - 2)$ that is the
2357 * contraction of index @p index_1 of a tensor @p src1 of rank @p rank_1 with
2358 * the index @p index_2 of a tensor @p src2 of rank @p rank_2:
2359 * @f[
2360 * \text{result}_{i_1,\ldots,i_{r1},j_1,\ldots,j_{r2}}
2361 * = \sum_{k}
2362 * \text{left}_{i_1,\ldots,k,\ldots,i_{r1}}
2363 * \text{right}_{j_1,\ldots,k,\ldots,j_{r2}}
2364 * @f]
2365 *
2366 * If for example the first index (<code>index_1==0</code>) of a tensor
2367 * <code>t1</code> shall be contracted with the third index
2368 * (<code>index_2==2</code>) of a tensor <code>t2</code>, this function should
2369 * be invoked as
2370 * @code
2371 * contract<0, 2>(t1, t2);
2372 * @endcode
2373 *
2374 * @note The position of the index is counted from 0, i.e.,
2375 * $0\le\text{index}_i<\text{range}_i$.
2376 *
2377 * @note In case the contraction yields a tensor of rank 0 the scalar number
2378 * is returned as an unwrapped number type.
2379 *
2380 * @relatesalso Tensor
2381 */
2382 template <int index_1,
2383 int index_2,
2384 int rank_1,
2385 int rank_2,
2386 int dim,
2387 typename Number,
2388 typename OtherNumber>
2389 constexpr inline DEAL_II_ALWAYS_INLINE
2390 typename Tensor<rank_1 + rank_2 - 2,
2391 dim,
2392 typename ProductType<Number, OtherNumber>::type>::tensor_type
2393 contract(const Tensor<rank_1, dim, Number> &src1,
2394 const Tensor<rank_2, dim, OtherNumber> &src2)
2395 {
2396 Assert(0 <= index_1 && index_1 < rank_1,
2397 ExcMessage(
2398 "The specified index_1 must lie within the range [0,rank_1)"));
2399 Assert(0 <= index_2 && index_2 < rank_2,
2400 ExcMessage(
2401 "The specified index_2 must lie within the range [0,rank_2)"));
2402
2403 using namespace TensorAccessors;
2404 using namespace TensorAccessors::internal;
2405
2406 // Reorder index_1 to the end of src1:
2407 const ReorderedIndexView<index_1, rank_1, const Tensor<rank_1, dim, Number>>
2408 reord_01 = reordered_index_view<index_1, rank_1>(src1);
2409
2410 // Reorder index_2 to the end of src2:
2411 const ReorderedIndexView<index_2,
2412 rank_2,
2413 const Tensor<rank_2, dim, OtherNumber>>
2414 reord_02 = reordered_index_view<index_2, rank_2>(src2);
2415
2416 typename Tensor<rank_1 + rank_2 - 2,
2417 dim,
2418 typename ProductType<Number, OtherNumber>::type>::tensor_type
2419 result{};
2420 TensorAccessors::contract<1, rank_1, rank_2, dim>(result, reord_01, reord_02);
2421 return result;
2422 }
2423
2424
2425 /**
2426 * Generic contraction of two pairs of indices of two tensors of arbitrary
2427 * rank: Return a tensor of rank $(\text{rank}_1 + \text{rank}_2 - 4)$ that is
2428 * the contraction of index @p index_1 with index @p index_2, and index @p
2429 * index_3 with index @p index_4 of a tensor @p src1 of rank @p rank_1 and a
2430 * tensor @p src2 of rank @p rank_2:
2431 * @f[
2432 * \text{result}_{i_1,\ldots,i_{r1},j_1,\ldots,j_{r2}}
2433 * = \sum_{k, l}
2434 * \text{left}_{i_1,\ldots,k,\ldots,l,\ldots,i_{r1}}
2435 * \text{right}_{j_1,\ldots,k,\ldots,l\ldots,j_{r2}}
2436 * @f]
2437 *
2438 * If for example the first index (<code>index_1==0</code>) shall be
2439 * contracted with the third index (<code>index_2==2</code>), and the second
2440 * index (<code>index_3==1</code>) with the first index
2441 * (<code>index_4==0</code>) of a tensor <code>t2</code>, this function should
2442 * be invoked as
2443 * @code
2444 * double_contract<0, 2, 1, 0>(t1, t2);
2445 * @endcode
2446 *
2447 * @note The position of the index is counted from 0, i.e.,
2448 * $0\le\text{index}_i<\text{range}_i$.
2449 *
2450 * @note In case the contraction yields a tensor of rank 0 the scalar number
2451 * is returned as an unwrapped number type.
2452 *
2453 * @relatesalso Tensor
2454 */
2455 template <int index_1,
2456 int index_2,
2457 int index_3,
2458 int index_4,
2459 int rank_1,
2460 int rank_2,
2461 int dim,
2462 typename Number,
2463 typename OtherNumber>
2464 constexpr inline
2465 typename Tensor<rank_1 + rank_2 - 4,
2466 dim,
2467 typename ProductType<Number, OtherNumber>::type>::tensor_type
2468 double_contract(const Tensor<rank_1, dim, Number> &src1,
2469 const Tensor<rank_2, dim, OtherNumber> &src2)
2470 {
2471 Assert(0 <= index_1 && index_1 < rank_1,
2472 ExcMessage(
2473 "The specified index_1 must lie within the range [0,rank_1)"));
2474 Assert(0 <= index_3 && index_3 < rank_1,
2475 ExcMessage(
2476 "The specified index_3 must lie within the range [0,rank_1)"));
2477 Assert(index_1 != index_3,
2478 ExcMessage("index_1 and index_3 must not be the same"));
2479 Assert(0 <= index_2 && index_2 < rank_2,
2480 ExcMessage(
2481 "The specified index_2 must lie within the range [0,rank_2)"));
2482 Assert(0 <= index_4 && index_4 < rank_2,
2483 ExcMessage(
2484 "The specified index_4 must lie within the range [0,rank_2)"));
2485 Assert(index_2 != index_4,
2486 ExcMessage("index_2 and index_4 must not be the same"));
2487
2488 using namespace TensorAccessors;
2489 using namespace TensorAccessors::internal;
2490
2491 // Reorder index_1 to the end of src1:
2492 ReorderedIndexView<index_1, rank_1, const Tensor<rank_1, dim, Number>>
2493 reord_1 = TensorAccessors::reordered_index_view<index_1, rank_1>(src1);
2494
2495 // Reorder index_2 to the end of src2:
2496 ReorderedIndexView<index_2, rank_2, const Tensor<rank_2, dim, OtherNumber>>
2497 reord_2 = TensorAccessors::reordered_index_view<index_2, rank_2>(src2);
2498
2499 // Now, reorder index_3 to the end of src1. We have to make sure to
2500 // preserve the original ordering: index_1 has been removed. If
2501 // index_3 > index_1, we have to use (index_3 - 1) instead:
2502 ReorderedIndexView<
2503 (index_3 < index_1 ? index_3 : index_3 - 1),
2504 rank_1,
2505 ReorderedIndexView<index_1, rank_1, const Tensor<rank_1, dim, Number>>>
2506 reord_3 =
2507 TensorAccessors::reordered_index_view < index_3 < index_1 ? index_3 :
2508 index_3 - 1,
2509 rank_1 > (reord_1);
2510
2511 // Now, reorder index_4 to the end of src2. We have to make sure to
2512 // preserve the original ordering: index_2 has been removed. If
2513 // index_4 > index_2, we have to use (index_4 - 1) instead:
2514 ReorderedIndexView<
2515 (index_4 < index_2 ? index_4 : index_4 - 1),
2516 rank_2,
2517 ReorderedIndexView<index_2, rank_2, const Tensor<rank_2, dim, OtherNumber>>>
2518 reord_4 =
2519 TensorAccessors::reordered_index_view < index_4 < index_2 ? index_4 :
2520 index_4 - 1,
2521 rank_2 > (reord_2);
2522
2523 typename Tensor<rank_1 + rank_2 - 4,
2524 dim,
2525 typename ProductType<Number, OtherNumber>::type>::tensor_type
2526 result{};
2527 TensorAccessors::contract<2, rank_1, rank_2, dim>(result, reord_3, reord_4);
2528 return result;
2529 }
2530
2531
2532 /**
2533 * The scalar product, or (generalized) Frobenius inner product of two tensors
2534 * of equal rank: Return a scalar number that is the result of a full
2535 * contraction of a tensor @p left and @p right:
2536 * @f[
2537 * \sum_{i_1,\ldots,i_r}
2538 * \text{left}_{i_1,\ldots,i_r}
2539 * \text{right}_{i_1,\ldots,i_r}
2540 * @f]
2541 *
2542 * @relatesalso Tensor
2543 */
2544 template <int rank, int dim, typename Number, typename OtherNumber>
2545 constexpr inline DEAL_II_ALWAYS_INLINE
2546 typename ProductType<Number, OtherNumber>::type
2547 scalar_product(const Tensor<rank, dim, Number> &left,
2548 const Tensor<rank, dim, OtherNumber> &right)
2549 {
2550 typename ProductType<Number, OtherNumber>::type result{};
2551 TensorAccessors::contract<rank, rank, rank, dim>(result, left, right);
2552 return result;
2553 }
2554
2555
2556 /**
2557 * Full contraction of three tensors: Return a scalar number that is the
2558 * result of a full contraction of a tensor @p left of rank @p rank_1, a
2559 * tensor @p middle of rank $(\text{rank}_1+\text{rank}_2)$ and a tensor @p
2560 * right of rank @p rank_2:
2561 * @f[
2562 * \sum_{i_1,\ldots,i_{r1},j_1,\ldots,j_{r2}}
2563 * \text{left}_{i_1,\ldots,i_{r1}}
2564 * \text{middle}_{i_1,\ldots,i_{r1},j_1,\ldots,j_{r2}}
2565 * \text{right}_{j_1,\ldots,j_{r2}}
2566 * @f]
2567 *
2568 * @note Each of the three input tensors can be either a Tensor or
2569 * SymmetricTensor.
2570 *
2571 * @relatesalso Tensor
2572 */
2573 template <template <int, int, typename> class TensorT1,
2574 template <int, int, typename>
2575 class TensorT2,
2576 template <int, int, typename>
2577 class TensorT3,
2578 int rank_1,
2579 int rank_2,
2580 int dim,
2581 typename T1,
2582 typename T2,
2583 typename T3>
2584 constexpr inline DEAL_II_ALWAYS_INLINE
2585 typename ProductType<T1, typename ProductType<T2, T3>::type>::type
2586 contract3(const TensorT1<rank_1, dim, T1> &left,
2587 const TensorT2<rank_1 + rank_2, dim, T2> &middle,
2588 const TensorT3<rank_2, dim, T3> &right)
2589 {
2590 using return_type =
2591 typename ProductType<T1, typename ProductType<T2, T3>::type>::type;
2592 return TensorAccessors::contract3<rank_1, rank_2, dim, return_type>(left,
2593 middle,
2594 right);
2595 }
2596
2597
2598 /**
2599 * The outer product of two tensors of @p rank_1 and @p rank_2: Returns a
2600 * tensor of rank $(\text{rank}_1 + \text{rank}_2)$:
2601 * @f[
2602 * \text{result}_{i_1,\ldots,i_{r1},j_1,\ldots,j_{r2}}
2603 * = \text{left}_{i_1,\ldots,i_{r1}}\,\text{right}_{j_1,\ldots,j_{r2}.}
2604 * @f]
2605 *
2606 * @relatesalso Tensor
2607 */
2608 template <int rank_1,
2609 int rank_2,
2610 int dim,
2611 typename Number,
2612 typename OtherNumber>
2613 constexpr inline DEAL_II_ALWAYS_INLINE
2614 Tensor<rank_1 + rank_2, dim, typename ProductType<Number, OtherNumber>::type>
2615 outer_product(const Tensor<rank_1, dim, Number> &src1,
2616 const Tensor<rank_2, dim, OtherNumber> &src2)
2617 {
2618 typename Tensor<rank_1 + rank_2,
2619 dim,
2620 typename ProductType<Number, OtherNumber>::type>::tensor_type
2621 result{};
2622 TensorAccessors::contract<0, rank_1, rank_2, dim>(result, src1, src2);
2623 return result;
2624 }
2625
2626
2627 /**
2628 * @}
2629 */
2630 /**
2631 * @name Special operations on tensors of rank 1
2632 * @{
2633 */
2634
2635 /**
2636 * Return the cross product in 2d. This is just a rotation by 90 degrees
2637 * clockwise to compute the outer normal from a tangential vector. This
2638 * function is defined for all space dimensions to allow for dimension
2639 * independent programming (e.g. within switches over the space dimension),
2640 * but may only be called if the actual dimension of the arguments is two
2641 * (e.g. from the <tt>dim==2</tt> case in the switch).
2642 *
2643 * @relatesalso Tensor
2644 */
2645 template <int dim, typename Number>
2646 constexpr inline DEAL_II_ALWAYS_INLINE Tensor<1, dim, Number>
2647 cross_product_2d(const Tensor<1, dim, Number> &src)
2648 {
2649 Assert(dim == 2, ExcInternalError());
2650
2651 Tensor<1, dim, Number> result;
2652
2653 result[0] = src[1];
2654 result[1] = -src[0];
2655
2656 return result;
2657 }
2658
2659
2660 /**
2661 * Return the cross product of 2 vectors in 3d. This function is defined for
2662 * all space dimensions to allow for dimension independent programming (e.g.
2663 * within switches over the space dimension), but may only be called if the
2664 * actual dimension of the arguments is three (e.g. from the <tt>dim==3</tt>
2665 * case in the switch).
2666 *
2667 * @relatesalso Tensor
2668 */
2669 template <int dim, typename Number1, typename Number2>
2670 constexpr inline DEAL_II_ALWAYS_INLINE
2671 Tensor<1, dim, typename ProductType<Number1, Number2>::type>
2672 cross_product_3d(const Tensor<1, dim, Number1> &src1,
2673 const Tensor<1, dim, Number2> &src2)
2674 {
2675 Assert(dim == 3, ExcInternalError());
2676
2677 Tensor<1, dim, typename ProductType<Number1, Number2>::type> result;
2678
2679 if constexpr (dim == 3)
2680 {
2681 result[0] = src1[1] * src2[2] - src1[2] * src2[1];
2682 result[1] = src1[2] * src2[0] - src1[0] * src2[2];
2683 result[2] = src1[0] * src2[1] - src1[1] * src2[0];
2684 }
2685
2686 return result;
2687 }
2688
2689
2690 /**
2691 * @}
2692 */
2693 /**
2694 * @name Special operations on tensors of rank 2
2695 * @{
2696 */
2697
2698 /**
2699 * Compute the determinant of a tensor or rank 2.
2700 *
2701 * @relatesalso Tensor
2702 */
2703 template <int dim, typename Number>
2704 constexpr inline DEAL_II_ALWAYS_INLINE Number
2705 determinant(const Tensor<2, dim, Number> &t)
2706 {
2707 // Compute the determinant using the Laplace expansion of the
2708 // determinant. We expand along the last row.
2709 Number det = internal::NumberType<Number>::value(0.0);
2710
2711 for (unsigned int k = 0; k < dim; ++k)
2712 {
2713 Tensor<2, dim - 1, Number> minor;
2714 for (unsigned int i = 0; i < dim - 1; ++i)
2715 for (unsigned int j = 0; j < dim - 1; ++j)
2716 minor[i][j] = t[i][j < k ? j : j + 1];
2717
2718 const Number cofactor = ((k % 2 == 0) ? -1. : 1.) * determinant(minor);
2719
2720 det += t[dim - 1][k] * cofactor;
2721 }
2722
2723 return ((dim % 2 == 0) ? 1. : -1.) * det;
2724 }
2725
2726 /**
2727 * Specialization for dim==1.
2728 *
2729 * @relatesalso Tensor
2730 */
2731 template <typename Number>
2732 constexpr DEAL_II_ALWAYS_INLINE Number
2733 determinant(const Tensor<2, 1, Number> &t)
2734 {
2735 return t[0][0];
2736 }
2737
2738 /**
2739 * Specialization for dim==2.
2740 *
2741 * @relatesalso Tensor
2742 */
2743 template <typename Number>
2744 constexpr DEAL_II_ALWAYS_INLINE Number
2745 determinant(const Tensor<2, 2, Number> &t)
2746 {
2747 // hard-coded for efficiency reasons
2748 return t[0][0] * t[1][1] - t[1][0] * t[0][1];
2749 }
2750
2751 /**
2752 * Specialization for dim==3.
2753 *
2754 * @relatesalso Tensor
2755 */
2756 template <typename Number>
2757 constexpr DEAL_II_ALWAYS_INLINE Number
2758 determinant(const Tensor<2, 3, Number> &t)
2759 {
2760 // hard-coded for efficiency reasons
2761 const Number C0 = internal::NumberType<Number>::value(t[1][1] * t[2][2]) -
2762 internal::NumberType<Number>::value(t[1][2] * t[2][1]);
2763 const Number C1 = internal::NumberType<Number>::value(t[1][2] * t[2][0]) -
2764 internal::NumberType<Number>::value(t[1][0] * t[2][2]);
2765 const Number C2 = internal::NumberType<Number>::value(t[1][0] * t[2][1]) -
2766 internal::NumberType<Number>::value(t[1][1] * t[2][0]);
2767 return t[0][0] * C0 + t[0][1] * C1 + t[0][2] * C2;
2768 }
2769
2770
2771 /**
2772 * Compute and return the trace of a tensor of rank 2, i.e. the sum of its
2773 * diagonal entries.
2774 *
2775 * @relatesalso Tensor
2776 */
2777 template <int dim, typename Number>
2778 constexpr inline DEAL_II_ALWAYS_INLINE Number
2779 trace(const Tensor<2, dim, Number> &d)
2780 {
2781 Number t = d[0][0];
2782 for (unsigned int i = 1; i < dim; ++i)
2783 t += d[i][i];
2784 return t;
2785 }
2786
2787
2788 /**
2789 * Compute and return the inverse of the given tensor. Since the compiler can
2790 * perform the return value optimization, and since the size of the return
2791 * object is known, it is acceptable to return the result by value, rather
2792 * than by reference as a parameter.
2793 *
2794 * @relatesalso Tensor
2795 */
2796 template <int dim, typename Number>
2797 constexpr inline Tensor<2, dim, Number>
2798 invert(const Tensor<2, dim, Number> &)
2799 {
2800 Number return_tensor[dim][dim];
2801
2802 // if desired, take over the
2803 // inversion of a 4x4 tensor
2804 // from the FullMatrix
2805 AssertThrow(false, ExcNotImplemented());
2806
2807 return Tensor<2, dim, Number>(return_tensor);
2808 }
2809
2810
2811 #ifndef DOXYGEN
2812
2813 template <typename Number>
2814 constexpr inline DEAL_II_ALWAYS_INLINE Tensor<2, 1, Number>
2815 invert(const Tensor<2, 1, Number> &t)
2816 {
2817 Tensor<2, 1, Number> return_tensor;
2818
2819 return_tensor[0][0] = internal::NumberType<Number>::value(1.0 / t[0][0]);
2820
2821 return return_tensor;
2822 }
2823
2824
2825 template <typename Number>
2826 constexpr inline DEAL_II_ALWAYS_INLINE Tensor<2, 2, Number>
2827 invert(const Tensor<2, 2, Number> &t)
2828 {
2829 Tensor<2, 2, Number> return_tensor;
2830
2831 const Number inv_det_t = internal::NumberType<Number>::value(
2832 1.0 / (t[0][0] * t[1][1] - t[1][0] * t[0][1]));
2833 return_tensor[0][0] = t[1][1];
2834 return_tensor[0][1] = -t[0][1];
2835 return_tensor[1][0] = -t[1][0];
2836 return_tensor[1][1] = t[0][0];
2837 return_tensor *= inv_det_t;
2838
2839 return return_tensor;
2840 }
2841
2842 template <typename Number>
2843 constexpr inline DEAL_II_ALWAYS_INLINE Tensor<2, 3, Number>
2844 invert(const Tensor<2, 3, Number> &t)
2845 {
2846 Tensor<2, 3, Number> return_tensor;
2847
2848 const auto value = [](const auto &t) {
2849 return internal::NumberType<Number>::value(t);
2850 };
2851
2852 return_tensor[0][0] = value(t[1][1] * t[2][2]) - value(t[1][2] * t[2][1]);
2853 return_tensor[0][1] = value(t[0][2] * t[2][1]) - value(t[0][1] * t[2][2]);
2854 return_tensor[0][2] = value(t[0][1] * t[1][2]) - value(t[0][2] * t[1][1]);
2855 return_tensor[1][0] = value(t[1][2] * t[2][0]) - value(t[1][0] * t[2][2]);
2856 return_tensor[1][1] = value(t[0][0] * t[2][2]) - value(t[0][2] * t[2][0]);
2857 return_tensor[1][2] = value(t[0][2] * t[1][0]) - value(t[0][0] * t[1][2]);
2858 return_tensor[2][0] = value(t[1][0] * t[2][1]) - value(t[1][1] * t[2][0]);
2859 return_tensor[2][1] = value(t[0][1] * t[2][0]) - value(t[0][0] * t[2][1]);
2860 return_tensor[2][2] = value(t[0][0] * t[1][1]) - value(t[0][1] * t[1][0]);
2861
2862 const Number inv_det_t =
2863 value(1.0 / (t[0][0] * return_tensor[0][0] + t[0][1] * return_tensor[1][0] +
2864 t[0][2] * return_tensor[2][0]));
2865 return_tensor *= inv_det_t;
2866
2867 return return_tensor;
2868 }
2869
2870 #endif /* DOXYGEN */
2871
2872
2873 /**
2874 * Return the transpose of the given tensor.
2875 *
2876 * @relatesalso Tensor
2877 */
2878 template <int dim, typename Number>
2879 constexpr inline DEAL_II_ALWAYS_INLINE Tensor<2, dim, Number>
2880 transpose(const Tensor<2, dim, Number> &t)
2881 {
2882 Tensor<2, dim, Number> tt;
2883 for (unsigned int i = 0; i < dim; ++i)
2884 {
2885 tt[i][i] = t[i][i];
2886 for (unsigned int j = i + 1; j < dim; ++j)
2887 {
2888 tt[i][j] = t[j][i];
2889 tt[j][i] = t[i][j];
2890 };
2891 }
2892 return tt;
2893 }
2894
2895
2896 /**
2897 * Return the adjugate of the given tensor of rank 2.
2898 * The adjugate of a tensor $\mathbf A$ is defined as
2899 * @f[
2900 * \textrm{adj}\mathbf A
2901 * \dealcoloneq \textrm{det}\mathbf A \; \mathbf{A}^{-1}
2902 * \; .
2903 * @f]
2904 *
2905 * @note This requires that the tensor is invertible.
2906 *
2907 * @relatesalso Tensor
2908 */
2909 template <int dim, typename Number>
2910 constexpr Tensor<2, dim, Number>
2911 adjugate(const Tensor<2, dim, Number> &t)
2912 {
2913 return determinant(t) * invert(t);
2914 }
2915
2916
2917 /**
2918 * Return the cofactor of the given tensor of rank 2.
2919 * The cofactor of a tensor $\mathbf A$ is defined as
2920 * @f[
2921 * \textrm{cof}\mathbf A
2922 * \dealcoloneq \textrm{det}\mathbf A \; \mathbf{A}^{-T}
2923 * = \left[ \textrm{adj}\mathbf A \right]^{T} \; .
2924 * @f]
2925 *
2926 * @note This requires that the tensor is invertible.
2927 *
2928 * @relatesalso Tensor
2929 */
2930 template <int dim, typename Number>
2931 constexpr Tensor<2, dim, Number>
2932 cofactor(const Tensor<2, dim, Number> &t)
2933 {
2934 return transpose(adjugate(t));
2935 }
2936
2937
2938 /**
2939 * Return the nearest orthogonal matrix
2940 * $\hat {\mathbf A}=\mathbf U \mathbf{V}^T$ by
2941 * combining the products of the singular value decomposition (SVD)
2942 * ${\mathbf A}=\mathbf U \mathbf S \mathbf V^T$ for a given input
2943 * ${\mathbf A}$, effectively replacing $\mathbf S$ with the identity matrix.
2944 *
2945 * This is a (nonlinear)
2946 * [projection
2947 * operation](https://en.wikipedia.org/wiki/Projection_(mathematics)) since when
2948 * applied twice, we have $\hat{\hat{\mathbf A}}=\hat{\mathbf A}$ as is easy to
2949 * see. (That is because the SVD of $\hat {\mathbf A}$ is simply
2950 * $\mathbf U \mathbf I \mathbf{V}^T$.) Furthermore, $\hat {\mathbf A}$ is
2951 * really an orthogonal matrix because orthogonal matrices have to satisfy
2952 * ${\hat {\mathbf A}}^T \hat {\mathbf A}={\mathbf I}$, which here implies
2953 * that
2954 * @f{align*}{
2955 * {\hat {\mathbf A}}^T \hat {\mathbf A}
2956 * &=
2957 * \left(\mathbf U \mathbf{V}^T\right)^T\left(\mathbf U \mathbf{V}^T\right)
2958 * \\
2959 * &=
2960 * \mathbf V \mathbf{U}^T
2961 * \mathbf U \mathbf{V}^T
2962 * \\
2963 * &=
2964 * \mathbf V \left(\mathbf{U}^T
2965 * \mathbf U\right) \mathbf{V}^T
2966 * \\
2967 * &=
2968 * \mathbf V \mathbf I \mathbf{V}^T
2969 * \\
2970 * &=
2971 * \mathbf V \mathbf{V}^T
2972 * \\
2973 * &=
2974 * \mathbf I
2975 * @f}
2976 * due to the fact that the $\mathbf U$ and $\mathbf V$ factors that come out
2977 * of the SVD are themselves orthogonal matrices.
2978 *
2979 * @param A The tensor for which to find the closest orthogonal tensor.
2980 * @tparam Number The type used to store the entries of the tensor.
2981 * Must be either `float` or `double`.
2982 * @pre In order to use this function, this program must be linked with the
2983 * LAPACK library.
2984 * @pre @p A must not be singular. This is because, conceptually, the problem
2985 * to be solved here is trying to find a matrix $\hat{\mathbf A}$ that
2986 * minimizes some kind of distance from $\mathbf A$ while satisfying the
2987 * quadratic constraint
2988 * ${\hat {\mathbf A}}^T \hat {\mathbf A}={\mathbf I}$. This is not so
2989 * dissimilar to the kind of problem where one wants to find a vector
2990 * $\hat{\mathbf x}\in{\mathbb R}^n$ that minimizes the quadratic objective
2991 * function $\|\hat {\mathbf x} - \mathbf x\|^2$ for a given $\mathbf x$
2992 * subject to the constraint $\|\mathbf x\|^2=1$ -- in other
2993 * words, we are seeking the point $\hat{\mathbf x}$ on the unit sphere
2994 * that is closest to $\mathbf x$. This problem has a solution for all
2995 * $\mathbf x$ except if $\mathbf x=0$. The corresponding condition
2996 * for the problem we are considering here is that $\mathbf A$ must not
2997 * have a zero eigenvalue.
2998 *
2999 * @relatesalso Tensor
3000 */
3001 template <int dim, typename Number>
3002 Tensor<2, dim, Number>
3003 project_onto_orthogonal_tensors(const Tensor<2, dim, Number> &A);
3004
3005
3006 /**
3007 * Return the $l_1$ norm of the given rank-2 tensor, where
3008 * $\|\mathbf T\|_1 = \max_j \sum_i |T_{ij}|$
3009 * (maximum of the sums over columns).
3010 *
3011 * @relatesalso Tensor
3012 */
3013 template <int dim, typename Number>
3014 inline Number
3015 l1_norm(const Tensor<2, dim, Number> &t)
3016 {
3017 Number max = internal::NumberType<Number>::value(0.0);
3018 for (unsigned int j = 0; j < dim; ++j)
3019 {
3020 Number sum = internal::NumberType<Number>::value(0.0);
3021 for (unsigned int i = 0; i < dim; ++i)
3022 sum += numbers::NumberTraits<Number>::abs(t[i][j]);
3023
3024 if (sum > max)
3025 max = sum;
3026 }
3027
3028 return max;
3029 }
3030
3031
3032 /**
3033 * Return the $l_\infty$ norm of the given rank-2 tensor, where
3034 * $\|\mathbf T\|_\infty = \max_i \sum_j |T_{ij}|$
3035 * (maximum of the sums over rows).
3036 *
3037 * @relatesalso Tensor
3038 */
3039 template <int dim, typename Number>
3040 inline Number
3041 linfty_norm(const Tensor<2, dim, Number> &t)
3042 {
3043 Number max = internal::NumberType<Number>::value(0.0);
3044 for (unsigned int i = 0; i < dim; ++i)
3045 {
3046 Number sum = internal::NumberType<Number>::value(0.0);
3047 for (unsigned int j = 0; j < dim; ++j)
3048 sum += numbers::NumberTraits<Number>::abs(t[i][j]);
3049
3050 if (sum > max)
3051 max = sum;
3052 }
3053
3054 return max;
3055 }
3056
3057 /**
3058 * @}
3059 */
3060
3061
3062 #ifndef DOXYGEN
3063
3064
3065 # ifdef DEAL_II_ADOLC_WITH_ADVANCED_BRANCHING
3066
3067 // Specialization of functions for ADOL-C number types when
3068 // the advanced branching feature is used
3069 template <int dim>
3070 inline adouble
3071 l1_norm(const Tensor<2, dim, adouble> &t)
3072 {
3073 adouble max = internal::NumberType<adouble>::value(0.0);
3074 for (unsigned int j = 0; j < dim; ++j)
3075 {
3076 adouble sum = internal::NumberType<adouble>::value(0.0);
3077 for (unsigned int i = 0; i < dim; ++i)
3078 sum += fabs(t[i][j]);
3079
3080 condassign(max, (sum > max), sum, max);
3081 }
3082
3083 return max;
3084 }
3085
3086
3087 template <int dim>
3088 inline adouble
3089 linfty_norm(const Tensor<2, dim, adouble> &t)
3090 {
3091 adouble max = internal::NumberType<adouble>::value(0.0);
3092 for (unsigned int i = 0; i < dim; ++i)
3093 {
3094 adouble sum = internal::NumberType<adouble>::value(0.0);
3095 for (unsigned int j = 0; j < dim; ++j)
3096 sum += fabs(t[i][j]);
3097
3098 condassign(max, (sum > max), sum, max);
3099 }
3100
3101 return max;
3102 }
3103
3104 # endif // DEAL_II_ADOLC_WITH_ADVANCED_BRANCHING
3105
3106
3107 #endif // DOXYGEN
3108
3109 DEAL_II_NAMESPACE_CLOSE
3110
3111 #endif