Debian Codegraph @

include/deal.II/base/symmetric_tensor.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2005 - 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_symmetric_tensor_h
16 #define dealii_symmetric_tensor_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/exceptions.h>
22 #include <deal.II/base/ndarray.h>
23 #include <deal.II/base/numbers.h>
24 #include <deal.II/base/table_indices.h>
25 #include <deal.II/base/template_constraints.h>
26 #include <deal.II/base/tensor.h>
27 #include <deal.II/base/types.h>
28
29 #include <array>
30
31 DEAL_II_NAMESPACE_OPEN
32
33 // Forward declaration
34 #ifndef DOXYGEN
35 template <int rank, int dim, typename Number = double>
36 class SymmetricTensor;
37 #endif
38
39 /**
40 * Return a unit symmetric tensor of rank 2, i.e., the
41 * $\text{dim}\times\text{dim}$ identity matrix $\mathbf I$.
42 * For example, if `dim==2`, then this matrix has the form
43 * @f[
44 * I_{2\times 2} = \begin{pmatrix} 1 & 0 \\ 0 & 1 \end{pmatrix}.
45 * @f]
46 *
47 * @relatesalso SymmetricTensor
48 */
49 template <int dim, typename Number = double>
50 DEAL_II_HOST DEAL_II_CONSTEXPR inline DEAL_II_ALWAYS_INLINE
51 SymmetricTensor<2, dim, Number>
52 unit_symmetric_tensor();
53
54 /**
55 * Return the tensor of rank 4 that, when multiplied by a symmetric rank 2
56 * tensor $\mathbf T$ returns the deviator $\text{dev}\ \mathbf T$. It is the
57 * operator representation of the linear deviator operator $\mathbb P$, also
58 * known as the volumetric projection tensor, calculated as:
59 * \f{align*}{
60 * \mathbb{P} &=\mathbb{S} -\frac{1}{\text{dim}} \mathbf I \otimes \mathbf I
61 * \\
62 * \mathcal{P}_{ijkl} &= \frac 12 \left(\delta_{ik} \delta_{jl} +
63 * \delta_{il} \delta_{jk} \right)
64 * - \frac{1}{\text{dim}} \delta_{ij} \delta_{kl}
65 * \f}
66 *
67 * For every tensor <tt>T</tt>, there holds the identity
68 * <tt>deviator<dim,Number>(T) == deviator_tensor<dim,Number>() * T</tt>,
69 * up to numerical round-off.
70 * \f[
71 * \text{dev}\mathbf T = \mathbb P : \mathbf T
72 * \f]
73 *
74 * @note The reason this operator representation is provided is to simplify
75 * taking derivatives of the deviatoric part of tensors:
76 * \f[
77 * \frac{\partial \text{dev}\mathbf{T}}{\partial \mathbf T} = \mathbb P.
78 * \f]
79 *
80 * @note This function uses $\frac{1}{\text{dim}}$ as the factor in the
81 * definition of the deviator, and that is unquestionably correct for
82 * three-dimensional models. However, whether this is the correct choice
83 * for two-dimensional models is something that depends on how one thinks
84 * about two-dimensional models. For example, in elasticity, one often
85 * does two-dimensional simulations that are thought of as cross sections
86 * of three-dimensional objects that are infinite in $z$-direction,
87 * with the assumption that the $z$-displacements are zero and that
88 * the $x$- and $y$-displacements do not vary in $z$-direction. Such
89 * models are often described as
90 * "<a
91 * href="https://en.wikipedia.org/wiki/Infinitesimal_strain_theory#Plane_strain">plane
92 * strain</a>", indicating that nonzero strain components are all in the $x$-$y$
93 * plane. The important point here is that while we only model two spatial
94 * variables, in the background *the model really is three-dimensional*.
95 * In these cases, the deviator should really contain $\frac{1}{3}$
96 * as the factor in front of the divergence, and in those cases you will
97 * not want to use the current function. On the other hand,
98 * there are of course also models that truly are two-dimensional --
99 * say the simulation of transport on the earth surface, or of the
100 * deformation of monolayers of
101 * [graphene](https://en.wikipedia.org/wiki/Graphene) (an inherently
102 * two-dimensional material). In those cases, the factor
103 * $\frac{1}{2}$ chosen in the definition of this function when using
104 * `dim==2` is correct. Whether or not the current function is right for
105 * you in two dimensions is therefore a question of what your model
106 * represents.
107 *
108 * @relatesalso SymmetricTensor
109 */
110 template <int dim, typename Number = double>
111 DEAL_II_HOST DEAL_II_CONSTEXPR inline DEAL_II_ALWAYS_INLINE
112 SymmetricTensor<4, dim, Number>
113 deviator_tensor();
114
115 /**
116 * Return the fourth-order symmetric identity tensor $\mathbb S$ which maps
117 * symmetric second-order tensors, such as $\mathbf A$, to themselves.
118 * \f[
119 * \mathbb S : \mathbf A = \mathbf A
120 * \f]
121 *
122 * Note that this tensor, even though it is the identity, has a somewhat funny
123 * form, and in particular does not only consist of zeros and ones. For
124 * example, for <tt>dim=2</tt>, the identity tensor has all zero entries
125 * except for
126 * \f[
127 * \mathcal{S}_{0000} = \mathcal{S}_{1111} = 1
128 * \f]
129 * \f[
130 * \mathcal{S}_{0101} = \mathcal{S}_{0110} = \mathcal{S}_{1001}
131 * = \mathcal{S}_{1010} = \frac 12.
132 * \f]
133 * In index notation, we can write the general form
134 * \f[
135 * \mathcal{S}_{ijkl} = \frac 12 \left( \delta_{ik} \delta_{jl} +
136 * \delta_{il} \delta_{jk} \right).
137 * \f]
138 * To see why this factor of $1 / 2$ is necessary, consider computing
139 * $\mathbf A= \mathbb I : \mathbf B$.
140 * For the element $A_{01}$ we have $A_{01} = \mathcal{S}_{0100} B_{00} +
141 * \mathcal{S}_{0111} B_{11} + \mathcal{S}_{0101} B_{01} +
142 * \mathcal{S}_{0110} B_{10}$. On the other hand, we need
143 * to have $A_{01} = B_{01}$, and symmetry implies $B_{01}=B_{10}$,
144 * leading to $A_{01} = (\mathcal{S}_{0101} + \mathcal{S}_{0110}) B_{01}$, or,
145 * again by symmetry, $\mathcal{S}_{0101} = \mathcal{S}_{0110} = \frac 12$.
146 * Similar considerations hold for the three-dimensional case.
147 *
148 * This issue is also explained in the introduction to step-44.
149 *
150 * @relatesalso SymmetricTensor
151 */
152 template <int dim, typename Number = double>
153 DEAL_II_HOST DEAL_II_CONSTEXPR inline DEAL_II_ALWAYS_INLINE
154 SymmetricTensor<4, dim, Number>
155 identity_tensor();
156
157 template <int dim, typename Number>
158 DEAL_II_HOST constexpr DEAL_II_ALWAYS_INLINE SymmetricTensor<2, dim, Number>
159 invert(const SymmetricTensor<2, dim, Number> &);
160
161 template <int dim, typename Number>
162 DEAL_II_HOST constexpr DEAL_II_ALWAYS_INLINE SymmetricTensor<4, dim, Number>
163 invert(const SymmetricTensor<4, dim, Number> &);
164
165 /**
166 * Compute and return the trace of a tensor of rank 2, i.e. the sum of its
167 * diagonal entries. The trace is the first invariant of a rank-2 tensor.
168 * \f[
169 * \text{tr} \mathbf A = \sum_i A_{ii}
170 * \f]
171 *
172 * @relatesalso SymmetricTensor
173 */
174 template <int dim2, typename Number>
175 DEAL_II_HOST constexpr inline DEAL_II_ALWAYS_INLINE Number
176 trace(const SymmetricTensor<2, dim2, Number> &);
177
178 /**
179 * Compute the deviator of a symmetric tensor, which is defined as
180 * $\text{dev} \mathbf T = \mathbf T -
181 * \frac{1}{\text{dim}} \text{tr}\mathbf T \; \mathbf I$, where $\mathbf I$
182 * is the identity operator. This
183 * quantity equals the original tensor minus its contractive or dilative
184 * component and refers to the shear in, for example, elasticity.
185 *
186 * @note This function uses $\frac{1}{\text{dim}}$ as the factor in the
187 * definition of the deviator, and that is unquestionably correct for
188 * three-dimensional models. However, whether this is the correct choice
189 * for two-dimensional models is something that depends on how one thinks
190 * about two-dimensional models. For example, in elasticity, one often
191 * does two-dimensional simulations that are thought of as cross sections
192 * of three-dimensional objects that are infinite in $z$-direction,
193 * with the assumption that the $z$-displacements are zero and that
194 * the $x$- and $y$-displacements do not vary in $z$-direction. Such
195 * models are often described as
196 * "<a
197 * href="https://en.wikipedia.org/wiki/Infinitesimal_strain_theory#Plane_strain">plane
198 * strain</a>", indicating that nonzero strain components are all in the $x$-$y$
199 * plane. The important point here is that while we only model two spatial
200 * variables, in the background *the model really is three-dimensional*.
201 * In these cases, the deviator should really contain $\frac{1}{3}$
202 * as the factor in front of the divergence, and in those cases you will
203 * not want to use the current function. On the other hand,
204 * there are of course also models that truly are two-dimensional --
205 * say the simulation of transport on the earth surface, or of the
206 * deformation of monolayers of
207 * [graphene](https://en.wikipedia.org/wiki/Graphene) (an inherently
208 * two-dimensional material). In those cases, the factor
209 * $\frac{1}{2}$ chosen in the definition of this function when using
210 * `dim==2` is correct. Whether or not the current function is right for
211 * you in two dimensions is therefore a question of what your model
212 * represents.
213 *
214 * @relatesalso SymmetricTensor
215 */
216 template <int dim, typename Number>
217 DEAL_II_HOST constexpr inline DEAL_II_ALWAYS_INLINE
218 SymmetricTensor<2, dim, Number>
219 deviator(const SymmetricTensor<2, dim, Number> &);
220
221 /**
222 * Compute the determinant of a rank 2 symmetric tensor. The determinant is
223 * also commonly referred to as the third invariant of rank-2 tensors.
224 *
225 * For a one-dimensional tensor, the determinant equals the only element and
226 * is therefore equivalent to the trace.
227 *
228 * For greater notational simplicity, there is also a
229 * <tt>third_invariant()</tt>
230 * function that returns the determinant of a tensor.
231 *
232 * @relatesalso SymmetricTensor
233 */
234 template <int dim, typename Number>
235 DEAL_II_HOST DEAL_II_CONSTEXPR inline DEAL_II_ALWAYS_INLINE Number
236 determinant(const SymmetricTensor<2, dim, Number> &);
237
238
239
240 namespace internal
241 {
242 // Workaround: The following 4 overloads are necessary to be able to
243 // compile the library with Apple Clang 8 and older. We should remove
244 // these overloads again when we bump the minimal required version to
245 // something later than clang-3.6 / Apple Clang 6.3.
246 template <int rank, int dim, typename T, typename U>
247 struct ProductTypeImpl<SymmetricTensor<rank, dim, T>, std::complex<U>>
248 {
249 using type =
250 SymmetricTensor<rank,
251 dim,
252 std::complex<typename ProductType<T, U>::type>>;
253 };
254
255 template <int rank, int dim, typename T, typename U>
256 struct ProductTypeImpl<SymmetricTensor<rank, dim, std::complex<T>>,
257 std::complex<U>>
258 {
259 using type =
260 SymmetricTensor<rank,
261 dim,
262 std::complex<typename ProductType<T, U>::type>>;
263 };
264
265 template <typename T, int rank, int dim, typename U>
266 struct ProductTypeImpl<std::complex<T>, SymmetricTensor<rank, dim, U>>
267 {
268 using type =
269 SymmetricTensor<rank,
270 dim,
271 std::complex<typename ProductType<T, U>::type>>;
272 };
273
274 template <int rank, int dim, typename T, typename U>
275 struct ProductTypeImpl<std::complex<T>,
276 SymmetricTensor<rank, dim, std::complex<U>>>
277 {
278 using type =
279 SymmetricTensor<rank,
280 dim,
281 std::complex<typename ProductType<T, U>::type>>;
282 };
283 // end workaround
284
285 /**
286 * A namespace for functions and classes that are internal to how the
287 * SymmetricTensor class (and its associate functions) works.
288 */
289 namespace SymmetricTensorImplementation
290 {
291 /**
292 * Compute the inverse of a symmetric tensor of a
293 * generic @p rank, @p dim and @p Number type.
294 */
295 template <int rank, int dim, typename Number>
296 struct Inverse;
297 } // namespace SymmetricTensorImplementation
298
299 /**
300 * A namespace for classes that are internal to how the SymmetricTensor
301 * class works.
302 */
303 namespace SymmetricTensorAccessors
304 {
305 /**
306 * Create a TableIndices<2> object where the first entries up to
307 * <tt>position-1</tt> are taken from previous_indices, and new_index is
308 * put at position <tt>position</tt>. The remaining indices remain in
309 * invalid state.
310 */
311 DEAL_II_HOST
312 DEAL_II_CONSTEXPR inline DEAL_II_ALWAYS_INLINE TableIndices<2>
313 merge(const TableIndices<2> &previous_indices,
314 const unsigned int new_index,
315 const unsigned int position)
316 {
317 AssertIndexRange(position, 2);
318
319 if (position == 0)
320 return {new_index, numbers::invalid_unsigned_int};
321 else
322 return {previous_indices[0], new_index};
323 }
324
325
326
327 /**
328 * Create a TableIndices<4> object where the first entries up to
329 * <tt>position-1</tt> are taken from previous_indices, and new_index is
330 * put at position <tt>position</tt>. The remaining indices remain in
331 * invalid state.
332 */
333 DEAL_II_HOST
334 DEAL_II_CONSTEXPR inline DEAL_II_ALWAYS_INLINE TableIndices<4>
335 merge(const TableIndices<4> &previous_indices,
336 const unsigned int new_index,
337 const unsigned int position)
338 {
339 AssertIndexRange(position, 4);
340
341 switch (position)
342 {
343 case 0:
344 return {new_index,
345 numbers::invalid_unsigned_int,
346 numbers::invalid_unsigned_int,
347 numbers::invalid_unsigned_int};
348 case 1:
349 return {previous_indices[0],
350 new_index,
351 numbers::invalid_unsigned_int,
352 numbers::invalid_unsigned_int};
353 case 2:
354 return {previous_indices[0],
355 previous_indices[1],
356 new_index,
357 numbers::invalid_unsigned_int};
358 case 3:
359 return {previous_indices[0],
360 previous_indices[1],
361 previous_indices[2],
362 new_index};
363 default:
364 DEAL_II_ASSERT_UNREACHABLE();
365 return {};
366 }
367 }
368
369
370 /**
371 * Typedef template magic denoting the result of a double contraction
372 * between two tensors or ranks rank1 and rank2. In general, this is a
373 * tensor of rank <tt>rank1+rank2-4</tt>, but if this is zero it is a
374 * single scalar Number. For this case, we have a specialization.
375 */
376 template <int rank1,
377 int rank2,
378 int dim,
379 typename Number,
380 typename OtherNumber = Number>
381 struct double_contraction_result
382 {
383 using value_type = typename ProductType<Number, OtherNumber>::type;
384 using type =
385 ::dealii::SymmetricTensor<rank1 + rank2 - 4, dim, value_type>;
386 };
387
388
389 /**
390 * Typedef template magic denoting the result of a double contraction
391 * between two tensors or ranks rank1 and rank2. In general, this is a
392 * tensor of rank <tt>rank1+rank2-4</tt>, but if this is zero it is a
393 * single scalar Number. For this case, we have a specialization.
394 */
395 template <int dim, typename Number, typename OtherNumber>
396 struct double_contraction_result<2, 2, dim, Number, OtherNumber>
397 {
398 using type = typename ProductType<Number, OtherNumber>::type;
399 };
400
401
402
403 /**
404 * Declaration of alias for the type of data structures which are used
405 * to store symmetric tensors. For example, for rank-2 symmetric tensors,
406 * we use a flat vector to store all the elements. On the other hand,
407 * symmetric rank-4 tensors are mappings from symmetric rank-2 tensors
408 * into symmetric rank-2 tensors, so they can be represented as matrices,
409 * etc.
410 *
411 * This information is probably of little interest to all except the
412 * accessor classes that need it. In particular, you shouldn't make any
413 * assumptions about the storage format in your application programs.
414 */
415 template <int rank, int dim, typename Number>
416 struct StorageType;
417
418 /**
419 * Specialization of StorageType for rank-2 tensors.
420 */
421 template <int dim, typename Number>
422 struct StorageType<2, dim, Number>
423 {
424 /**
425 * Number of independent components of a symmetric tensor of rank 2. We
426 * store only the upper right half of it.
427 */
428 static const unsigned int n_independent_components =
429 (dim * dim + dim) / 2;
430
431 /**
432 * Declare the type in which we actually store the data.
433 */
434 using base_tensor_type = Tensor<1, n_independent_components, Number>;
435 };
436
437
438
439 /**
440 * Specialization of StorageType for rank-4 tensors.
441 */
442 template <int dim, typename Number>
443 struct StorageType<4, dim, Number>
444 {
445 /**
446 * Number of independent components of a symmetric tensor of rank 2.
447 * Since rank-4 tensors are mappings between such objects, we need this
448 * information.
449 */
450 static const unsigned int n_rank2_components = (dim * dim + dim) / 2;
451
452 /**
453 * Number of independent components of a symmetric tensor of rank 4.
454 */
455 static const unsigned int n_independent_components =
456 (n_rank2_components *
457 StorageType<2, dim, Number>::n_independent_components);
458
459 /**
460 * Declare the type in which we actually store the data. Symmetric
461 * rank-4 tensors are mappings between symmetric rank-2 tensors, so we
462 * can represent the data as a matrix if we represent the rank-2 tensors
463 * as vectors.
464 */
465 using base_tensor_type = Tensor<2, n_rank2_components, Number>;
466 };
467
468
469
470 /**
471 * Switch type to select a tensor of rank 2 and dimension <tt>dim</tt>,
472 * switching on whether the tensor should be constant or not.
473 */
474 template <int rank, int dim, bool constness, typename Number>
475 struct AccessorTypes;
476
477 /**
478 * Switch type to select a tensor of rank 2 and dimension <tt>dim</tt>,
479 * switching on whether the tensor should be constant or not.
480 *
481 * Specialization for constant tensors.
482 */
483 template <int rank, int dim, typename Number>
484 struct AccessorTypes<rank, dim, true, Number>
485 {
486 using tensor_type = const ::dealii::SymmetricTensor<rank, dim, Number>;
487
488 using reference = const Number &;
489 };
490
491 /**
492 * Switch type to select a tensor of rank 2 and dimension <tt>dim</tt>,
493 * switching on whether the tensor should be constant or not.
494 *
495 * Specialization for non-constant tensors.
496 */
497 template <int rank, int dim, typename Number>
498 struct AccessorTypes<rank, dim, false, Number>
499 {
500 using tensor_type = ::dealii::SymmetricTensor<rank, dim, Number>;
501
502 using reference = Number &;
503 };
504
505
506 /**
507 * @internal
508 *
509 * Class that acts as accessor to elements of type SymmetricTensor. The
510 * template parameter <tt>constness</tt> may be either true or false, and
511 * indicates whether the objects worked on are constant or not (i.e. write
512 * access is only allowed if the value is false).
513 *
514 * Since with <tt>N</tt> indices, the effect of applying
515 * <tt>operator[]</tt> is getting access to something with <tt>N-1</tt>
516 * indices, we have to implement these accessor classes recursively, with
517 * stopping when we have only one index left. For the latter case, a
518 * specialization of this class is declared below, where calling
519 * <tt>operator[]</tt> gives you access to the objects actually stored by
520 * the tensor; the tensor class also makes sure that only those elements
521 * are actually accessed which we actually store, i.e. it reorders indices
522 * if necessary. The template parameter <tt>P</tt> indicates how many
523 * remaining indices there are. For a rank-2 tensor, <tt>P</tt> may be
524 * two, and when using <tt>operator[]</tt>, an object with <tt>P=1</tt>
525 * emerges.
526 *
527 * As stated for the entire namespace, you will not usually have to do
528 * with these classes directly, and should not try to use their interface
529 * directly as it may change without notice. In fact, since the
530 * constructors are made private, you will not even be able to generate
531 * objects of this class, as they are only thought as temporaries for
532 * access to elements of the table class, not for passing them around as
533 * arguments of functions, etc.
534 *
535 * This class is an adaptation of a similar class used for the Table
536 * class.
537 */
538 template <int rank, int dim, bool constness, int P, typename Number>
539 class Accessor
540 {
541 public:
542 /**
543 * Import two alias from the switch class above.
544 */
545 using reference =
546 typename AccessorTypes<rank, dim, constness, Number>::reference;
547 using tensor_type =
548 typename AccessorTypes<rank, dim, constness, Number>::tensor_type;
549
550 private:
551 /**
552 * Constructor. Take a reference to the tensor object which we will
553 * access.
554 *
555 * The second argument denotes the values of previous indices into the
556 * tensor. For example, for a rank-4 tensor, if P=2, then we will
557 * already have had two successive element selections (e.g. through
558 * <tt>tensor[1][2]</tt>), and the two index values have to be stored
559 * somewhere. This class therefore only makes use of the first rank-P
560 * elements of this array, but passes it on to the next level with P-1
561 * which fills the next entry, and so on.
562 *
563 * The constructor is made private in order to prevent you having such
564 * objects around. The only way to create such objects is via the
565 * <tt>Table</tt> class, which only generates them as temporary objects.
566 * This guarantees that the accessor objects go out of scope earlier
567 * than the parent object, avoid problems with data consistency.
568 */
569 DEAL_II_HOST
570 constexpr Accessor(tensor_type &tensor,
571 const TableIndices<rank> &previous_indices);
572
573 /**
574 * Copy constructor.
575 */
576 DEAL_II_HOST
577 constexpr DEAL_II_ALWAYS_INLINE
578 Accessor(const Accessor &) = default;
579
580 public:
581 /**
582 * Index operator.
583 */
584 DEAL_II_HOST
585 constexpr Accessor<rank, dim, constness, P - 1, Number>
586 operator[](const unsigned int i);
587
588 /**
589 * Index operator.
590 */
591 DEAL_II_HOST
592 constexpr Accessor<rank, dim, constness, P - 1, Number>
593 operator[](const unsigned int i) const;
594
595 private:
596 /**
597 * Store the data given to the constructor.
598 */
599 tensor_type &tensor;
600 const TableIndices<rank> previous_indices;
601
602 // Declare some other classes as friends. Make sure to work around bugs
603 // in some compilers:
604 template <int, int, typename>
605 friend class dealii::SymmetricTensor;
606 template <int, int, bool, int, typename>
607 friend class Accessor;
608 friend class ::dealii::SymmetricTensor<rank, dim, Number>;
609 friend class Accessor<rank, dim, constness, P + 1, Number>;
610 };
611
612
613
614 /**
615 * @internal Accessor class for SymmetricTensor. This is the
616 * specialization for the last index, which actually allows access to the
617 * elements of the table, rather than recursively returning access objects
618 * for further subsets. The same holds for this specialization as for the
619 * general template; see there for more information.
620 */
621 template <int rank, int dim, bool constness, typename Number>
622 class Accessor<rank, dim, constness, 1, Number>
623 {
624 public:
625 /**
626 * Import two alias from the switch class above.
627 */
628 using reference =
629 typename AccessorTypes<rank, dim, constness, Number>::reference;
630 using tensor_type =
631 typename AccessorTypes<rank, dim, constness, Number>::tensor_type;
632
633 private:
634 /**
635 * Constructor. Take a reference to the tensor object which we will
636 * access.
637 *
638 * The second argument denotes the values of previous indices into the
639 * tensor. For example, for a rank-4 tensor, if P=2, then we will
640 * already have had two successive element selections (e.g. through
641 * <tt>tensor[1][2]</tt>), and the two index values have to be stored
642 * somewhere. This class therefore only makes use of the first rank-P
643 * elements of this array, but passes it on to the next level with P-1
644 * which fills the next entry, and so on.
645 *
646 * For this particular specialization, i.e. for P==1, all but the last
647 * index are already filled.
648 *
649 * The constructor is made private in order to prevent you having such
650 * objects around. The only way to create such objects is via the
651 * <tt>Table</tt> class, which only generates them as temporary objects.
652 * This guarantees that the accessor objects go out of scope earlier
653 * than the parent object, avoid problems with data consistency.
654 */
655 DEAL_II_HOST
656 constexpr Accessor(tensor_type &tensor,
657 const TableIndices<rank> &previous_indices);
658
659 /**
660 * Copy constructor.
661 */
662 DEAL_II_HOST
663 constexpr DEAL_II_ALWAYS_INLINE
664 Accessor(const Accessor &) = default;
665
666 public:
667 /**
668 * Index operator.
669 */
670 DEAL_II_HOST
671 constexpr reference
672 operator[](const unsigned int);
673
674 /**
675 * Index operator.
676 */
677 DEAL_II_HOST
678 constexpr reference
679 operator[](const unsigned int) const;
680
681 private:
682 /**
683 * Store the data given to the constructor.
684 */
685 tensor_type &tensor;
686 const TableIndices<rank> previous_indices;
687
688 // Declare some other classes as friends. Make sure to work around bugs
689 // in some compilers:
690 template <int, int, typename>
691 friend class dealii::SymmetricTensor;
692 template <int, int, bool, int, typename>
693 friend class SymmetricTensorAccessors::Accessor;
694 friend class ::dealii::SymmetricTensor<rank, dim, Number>;
695 friend class SymmetricTensorAccessors::
696 Accessor<rank, dim, constness, 2, Number>;
697 };
698 } // namespace SymmetricTensorAccessors
699 } // namespace internal
700
701
702
703 /**
704 * Provide a class that stores symmetric tensors of rank 2,4,... efficiently,
705 * i.e. only store those off-diagonal elements of the full tensor that are not
706 * redundant. For example, for symmetric $2\times 2$ tensors, this would be the
707 * elements 11, 22, and 12, while the element 21 is equal to the 12 element.
708 * Within this documentation, second order symmetric tensors are denoted as
709 * bold-faced upper-case Latin letters such as $\mathbf A, \mathbf B, \dots$
710 * or bold-faced Greek letters such as $\boldsymbol{\varepsilon}$,
711 * $\boldsymbol{\sigma}$. The Cartesian coordinates of a second-order tensor
712 * such as $\mathbf A$ are represented as $A_{ij}$ where $i,j$ are indices
713 * ranging from 0 to <tt>dim-1</tt>.
714 *
715 * Using this class for symmetric tensors of rank 2 has advantages over
716 * matrices in many cases since the dimension is known to the compiler as well
717 * as the location of the data. It is therefore possible to produce far more
718 * efficient code than for matrices with runtime-dependent dimension. It is
719 * also more efficient than using the more general <tt>Tensor</tt> class,
720 * since fewer elements are stored, and the class automatically makes sure that
721 * the tensor represents a symmetric object.
722 *
723 * For tensors of higher rank, the savings in storage are even higher. For
724 * example for the $3 \times 3 \times 3 \times 3$ tensors of rank 4, only 36
725 * instead of the full 81 entries have to be stored. These rank 4 tensors are
726 * denoted by blackboard-style upper-case Latin letters such as $\mathbb A$
727 * with components $\mathcal{A}_{ijkl}$.
728 *
729 * While the definition of a symmetric rank-2 tensor is obvious, tensors of
730 * rank 4 are considered symmetric if they are operators mapping symmetric
731 * rank-2 tensors onto symmetric rank-2 tensors. This so-called minor symmetry
732 * of the rank 4 tensor requires that for every set of four indices
733 * $i, j, k, l$, the identity $\mathcal{C}_{ijkl} = \mathcal{C}_{jikl} =
734 * \mathcal{C}_{ijlk}$ holds. However, it does not imply the relation
735 * $\mathcal{C}_{ijkl} = \mathcal{C}_{klij}$.
736 * Consequently, symmetric tensors of rank 4 as understood here are only
737 * tensors that map symmetric tensors onto symmetric tensors, but they do not
738 * necessarily induce a symmetric scalar product $\mathbf A : \mathbb C :
739 * \mathbf B = \mathbf B : \mathbb C : \mathbf A$ or even
740 * a positive (semi-)definite form $\mathbf A : \mathbb C : \mathbf A$, where
741 * $\mathbf A, \mathbf B$ are symmetric rank-2 tensors and the colon indicates
742 * the common double-index contraction that acts as a scalar product for
743 * symmetric tensors.
744 *
745 * Symmetric tensors are most often used in structural and fluid
746 * mechanics, where strains and stresses are usually symmetric
747 * tensors, and the stress-strain relationship is given by a symmetric
748 * rank-4 tensor.
749 *
750 * @note Symmetric tensors only exist with even numbers of indices. In
751 * other words, the only objects that you can use are
752 * <tt>SymmetricTensor<2,dim></tt>, <tt>SymmetricTensor<4,dim></tt>, etc, but
753 * <tt>SymmetricTensor<1,dim></tt> and <tt>SymmetricTensor<3,dim></tt> do not
754 * exist and their use will most likely lead to compiler errors.
755 *
756 *
757 * <h3>Accessing elements</h3>
758 *
759 * The elements of a tensor $\mathbb C$ can be accessed using the bracket
760 * operator, i.e. for a tensor of rank 4, <tt>C[0][1][0][1]</tt> accesses the
761 * element $\mathcal{C}_{0101}$. This access can be used for both reading
762 * and writing (if the tensor is non-constant at least). You may also perform
763 * other operations on it, although that may lead to confusing situations
764 * because several elements of the tensor are stored at the same location. For
765 * example, for a rank-2 tensor that is assumed to be zero at the beginning,
766 * writing <tt>A[0][1]+=1; A[1][0]+=1;</tt> will lead to the same element
767 * being increased by one <em>twice</em>, because even though the accesses use
768 * different indices, the elements that are accessed are symmetric and
769 * therefore stored at the same location. It may therefore be useful in
770 * application programs to restrict operations on individual elements to
771 * simple reads or writes.
772 *
773 * @ingroup geomprimitives
774 */
775 template <int rank_, int dim, typename Number>
776 class SymmetricTensor
777 {
778 public:
779 static_assert(rank_ % 2 == 0, "A SymmetricTensor must have even rank!");
780
781 /**
782 * Provide a way to get the dimension of an object without explicit
783 * knowledge of it's data type. Implementation is this way instead of
784 * providing a function <tt>dimension()</tt> because now it is possible to
785 * get the dimension at compile time without the expansion and preevaluation
786 * of an inlined function; the compiler may therefore produce more efficient
787 * code and you may use this value to declare other data types.
788 */
789 static constexpr unsigned int dimension = dim;
790
791 /**
792 * Publish the rank of this tensor to the outside world.
793 */
794 static const unsigned int rank = rank_;
795
796 /**
797 * An integer denoting the number of independent components that fully
798 * describe a symmetric tensor. In $d$ space dimensions, this number equals
799 * $\frac 12 (d^2+d)$ for symmetric tensors of rank 2.
800 */
801 static constexpr unsigned int n_independent_components =
802 internal::SymmetricTensorAccessors::StorageType<rank_, dim, Number>::
803 n_independent_components;
804
805 /**
806 * Default constructor. Creates a tensor with all entries equal to zero.
807 */
808 DEAL_II_HOST
809 constexpr DEAL_II_ALWAYS_INLINE
810 SymmetricTensor() = default;
811
812 /**
813 * Constructor. Generate a symmetric tensor from a general one. Assumes that
814 * @p t is already symmetric, and in debug mode this is in fact checked.
815 * Note that no provision is made to assure that the tensor is symmetric
816 * only up to round-off error: if the incoming tensor is not exactly
817 * symmetric, then an exception is thrown. If you know that incoming tensor
818 * is symmetric only up to round-off, then you may want to call the
819 * <tt>symmetrize()</tt> function first. If you aren't sure, it is good
820 * practice to check before calling <tt>symmetrize()</tt>.
821 *
822 * Because we check for symmetry via a non-constexpr function call, you will
823 * have to use the symmetrize() function in constexpr contexts instead.
824 */
825 template <typename OtherNumber>
826 explicit SymmetricTensor(const Tensor<2, dim, OtherNumber> &t);
827
828 /**
829 * A constructor that creates a symmetric tensor from an array holding its
830 * independent elements. Using this constructor assumes that the caller
831 * knows the order in which elements are stored in symmetric tensors; its
832 * use is therefore discouraged, but if you think you want to use it anyway
833 * you can query the order of elements using the unrolled_index() function.
834 *
835 * This constructor is currently only implemented for symmetric tensors of
836 * rank 2.
837 *
838 * The size of the array passed is equal to
839 * SymmetricTensor<rank_,dim>::n_independent_components; the reason for using
840 * the object from the internal namespace is to work around bugs in some
841 * older compilers.
842 */
843 DEAL_II_HOST
844 constexpr SymmetricTensor(const Number (&array)[n_independent_components]);
845
846 /**
847 * Copy constructor from tensors with different underlying scalar type. This
848 * obviously requires that the @p OtherNumber type is convertible to @p
849 * Number.
850 */
851 template <typename OtherNumber>
852 DEAL_II_HOST constexpr explicit SymmetricTensor(
853 const SymmetricTensor<rank_, dim, OtherNumber> &initializer);
854
855 /**
856 * Assignment operator from symmetric tensors with different underlying scalar
857 * type.
858 * This obviously requires that the @p OtherNumber type is convertible to
859 * @p Number.
860 */
861 template <typename OtherNumber>
862 DEAL_II_HOST constexpr SymmetricTensor &
863 operator=(const SymmetricTensor<rank_, dim, OtherNumber> &rhs);
864
865 /**
866 * This operator assigns a scalar to a tensor. To avoid confusion with what
867 * exactly it means to assign a scalar value to a tensor, zero is the only
868 * value allowed for <tt>d</tt>, allowing the intuitive notation
869 * $\mathbf A = 0$ to reset all elements of the tensor to zero.
870 */
871 DEAL_II_HOST
872 constexpr SymmetricTensor &
873 operator=(const Number &d);
874
875 /**
876 * Convert the present symmetric tensor into a full tensor with the same
877 * elements, but using the different storage scheme of full tensors.
878 */
879 DEAL_II_HOST
880 constexpr operator Tensor<rank_, dim, Number>() const;
881
882 /**
883 * Test for equality of two tensors.
884 */
885 DEAL_II_HOST
886 constexpr bool
887 operator==(const SymmetricTensor &) const;
888
889 /**
890 * Test for inequality of two tensors.
891 */
892 DEAL_II_HOST
893 constexpr bool
894 operator!=(const SymmetricTensor &) const;
895
896 /**
897 * Add another tensor.
898 */
899 template <typename OtherNumber>
900 DEAL_II_HOST constexpr SymmetricTensor &
901 operator+=(const SymmetricTensor<rank_, dim, OtherNumber> &);
902
903 /**
904 * Subtract another tensor.
905 */
906 template <typename OtherNumber>
907 DEAL_II_HOST constexpr SymmetricTensor &
908 operator-=(const SymmetricTensor<rank_, dim, OtherNumber> &);
909
910 /**
911 * Scale the tensor by <tt>factor</tt>, i.e. multiply all components by
912 * <tt>factor</tt>.
913 */
914 template <typename OtherNumber>
915 DEAL_II_HOST constexpr SymmetricTensor &
916 operator*=(const OtherNumber &factor);
917
918 /**
919 * Scale the tensor by <tt>1/factor</tt>.
920 */
921 template <typename OtherNumber>
922 DEAL_II_HOST constexpr SymmetricTensor &
923 operator/=(const OtherNumber &factor);
924
925 /**
926 * Unary minus operator. Negate all entries of a tensor.
927 */
928 DEAL_II_HOST
929 constexpr SymmetricTensor
930 operator-() const;
931
932 /**
933 * Double contraction product between the present symmetric tensor and a
934 * tensor of rank 2. For example, if the present object is the symmetric
935 * rank-2 tensor $\mathbf{A}$ and it is multiplied by another symmetric
936 * rank-2 tensor $\mathbf{B}$, then the result is the scalar-product double
937 * contraction $\mathbf A : \mathbf B = \sum_{i,j} A_{ij} B_{ij}$.
938 * In this case, the return value evaluates to a single
939 * scalar. While it is possible to define other scalar products (and
940 * associated induced norms), this one seems to be the most appropriate one.
941 *
942 * If the present object is a rank-4 tensor such as $\mathbb A$, then the
943 * result is a rank-2 tensor $\mathbf C = \mathbb A : \mathbf B$, i.e.,
944 * the operation contracts over the last two indices of the present object
945 * and the indices of the argument, and the result is a tensor of rank 2
946 * ($C_{ij} = \sum_{k,l} \mathcal{A}_{ijkl} B_{kl}$).
947 *
948 * Note that the multiplication operator for symmetric tensors is defined to
949 * be a double contraction over two indices, while it is defined as a single
950 * contraction over only one index for regular <tt>Tensor</tt> objects. For
951 * symmetric tensors it therefore acts in a way that is commonly denoted by
952 * a "colon multiplication" in the mathematical literature (the two dots of
953 * the colon suggesting that it is a contraction over two indices), which
954 * corresponds to a scalar product between tensors.
955 *
956 * It is worth pointing out that this definition of `operator*` between
957 * symmetric tensors is different to how the (in general non-symmetric)
958 * Tensor class defines `operator*`, namely as the single-contraction
959 * product over the last index of the first operand and the first index of
960 * the second operand. For the double contraction of Tensor objects,
961 * you will need to use the `double_contract()` function.
962 *
963 * To maintain at least a modicum of resemblance between the interfaces
964 * of Tensor and SymmetricTensor, there are also global functions
965 * double_contract() for symmetric tensors that then do the same work
966 * as this operator. However, rather than returning the result as a return
967 * value, they write it into the first argument to the function in the same
968 * way as the corresponding functions for the Tensor class do things.
969 *
970 * @note The origin of the difference in how `operator*()` is implemented between
971 * Tensor and SymmetricTensor is that for the former, the product between
972 * two Tensor objects of same rank and dimension results in another Tensor
973 * object -- that it, `operator*()` corresponds to the multiplicative group
974 * action within the group of tensors. On the other hand, there is no
975 * corresponding multiplicative group action with the set of symmetric
976 * tensors because, in general, the product of two symmetric tensors is a
977 * *nonsymmetric* tensor. As a consequence, for a mathematician, it is clear
978 * that `operator*()` for symmetric tensors must have a different meaning:
979 * namely the *dot* or *scalar product* that maps two symmetric tensors of
980 * rank 2 to a scalar. This corresponds to the double-dot (colon) operator
981 * whose meaning is then extended to the product of any two even-ranked
982 * symmetric tensors.
983 */
984 template <typename OtherNumber>
985 DEAL_II_HOST DEAL_II_CONSTEXPR typename internal::SymmetricTensorAccessors::
986 double_contraction_result<rank_, 2, dim, Number, OtherNumber>::type
987 operator*(const SymmetricTensor<2, dim, OtherNumber> &s) const;
988
989 /**
990 * Contraction over the last two indices of the present object with the first
991 * two indices of the rank-4 symmetric tensor given as argument.
992 */
993 template <typename OtherNumber>
994 DEAL_II_HOST DEAL_II_CONSTEXPR typename internal::SymmetricTensorAccessors::
995 double_contraction_result<rank_, 4, dim, Number, OtherNumber>::type
996 operator*(const SymmetricTensor<4, dim, OtherNumber> &s) const;
997
998 /**
999 * Return a read-write reference to the indicated element.
1000 */
1001 DEAL_II_HOST
1002 constexpr Number &
1003 operator()(const TableIndices<rank_> &indices);
1004
1005 /**
1006 * Return a @p const reference to the value referred to by the argument.
1007 */
1008 DEAL_II_HOST
1009 constexpr const Number &
1010 operator()(const TableIndices<rank_> &indices) const;
1011
1012 /**
1013 * Access the elements of a row of this symmetric tensor. This function is
1014 * called for constant tensors.
1015 */
1016 DEAL_II_HOST
1017 constexpr internal::SymmetricTensorAccessors::
1018 Accessor<rank_, dim, true, rank_ - 1, Number>
1019 operator[](const unsigned int row) const;
1020
1021 /**
1022 * Access the elements of a row of this symmetric tensor. This function is
1023 * called for non-constant tensors.
1024 */
1025 DEAL_II_HOST
1026 constexpr internal::SymmetricTensorAccessors::
1027 Accessor<rank_, dim, false, rank_ - 1, Number>
1028 operator[](const unsigned int row);
1029
1030 /**
1031 * Return a @p const reference to the value referred to by the argument.
1032 *
1033 * Exactly the same as operator().
1034 */
1035 DEAL_II_HOST
1036 constexpr const Number &
1037 operator[](const TableIndices<rank_> &indices) const;
1038
1039 /**
1040 * Return a read-write reference to the indicated element.
1041 *
1042 * Exactly the same as operator().
1043 */
1044 DEAL_II_HOST
1045 constexpr Number &
1046 operator[](const TableIndices<rank_> &indices);
1047
1048 /**
1049 * Access to an element according to unrolled index. The function
1050 * <tt>s.access_raw_entry(unrolled_index)</tt> does the same as
1051 * <tt>s[s.unrolled_to_component_indices(unrolled_index)]</tt>, but more
1052 * efficiently.
1053 */
1054 DEAL_II_HOST
1055 constexpr const Number &
1056 access_raw_entry(const unsigned int unrolled_index) const;
1057
1058 /**
1059 * Access to an element according to unrolled index. The function
1060 * <tt>s.access_raw_entry(unrolled_index)</tt> does the same as
1061 * <tt>s[s.unrolled_to_component_indices(unrolled_index)]</tt>, but more
1062 * efficiently.
1063 */
1064 DEAL_II_HOST
1065 constexpr Number &
1066 access_raw_entry(const unsigned int unrolled_index);
1067
1068 /**
1069 * Return the Frobenius-norm of a tensor, i.e. the square root of the sum of
1070 * squares of all entries. This norm is induced by the scalar product
1071 * defined above for two symmetric tensors. Note that it includes <i>all</i>
1072 * entries of the tensor, counting symmetry, not only the unique ones (for
1073 * example, for rank-2 tensors, this norm includes adding up the squares of
1074 * upper right as well as lower left entries, not just one of them, although
1075 * they are equal for symmetric tensors).
1076 */
1077 DEAL_II_HOST
1078 constexpr typename numbers::NumberTraits<Number>::real_type
1079 norm() const;
1080
1081 /**
1082 * Tensor objects can be unrolled by simply pasting all elements into one
1083 * long vector, but for this an order of elements has to be defined. For
1084 * symmetric tensors, this function returns which index within the range
1085 * <code>[0,n_independent_components)</code> the given entry in a symmetric
1086 * tensor has.
1087 */
1088 static DEAL_II_HOST constexpr unsigned int
1089 component_to_unrolled_index(const TableIndices<rank_> &indices);
1090
1091 /**
1092 * The opposite of the previous function: given an index $i$ in the unrolled
1093 * form of the tensor, return what set of indices $(k,l)$ (for rank-2
1094 * tensors) or $(k,l,m,n)$ (for rank-4 tensors) corresponds to it.
1095 */
1096 static DEAL_II_HOST constexpr TableIndices<rank_>
1097 unrolled_to_component_indices(const unsigned int i);
1098
1099 /**
1100 * Reset all values to zero.
1101 *
1102 * Note that this is partly inconsistent with the semantics of the @p
1103 * clear() member functions of the standard library containers and of
1104 * several other classes within deal.II, which not only reset the values of
1105 * stored elements to zero, but release all memory and return the object
1106 * into an empty state. However, since the size of objects of the present
1107 * type is determined by its template parameters, resizing is not an option,
1108 * and indeed the state where all elements have a zero value is the state
1109 * right after construction of such an object.
1110 */
1111 DEAL_II_HOST
1112 constexpr void
1113 clear();
1114
1115 /**
1116 * Determine an estimate for the memory consumption (in bytes) of this
1117 * object.
1118 */
1119 static DEAL_II_HOST constexpr std::size_t
1120 memory_consumption();
1121
1122 /**
1123 * Read or write the data of this object to or from a stream for the purpose
1124 * of serialization using the [BOOST serialization
1125 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
1126 */
1127 template <class Archive>
1128 void
1129 serialize(Archive &ar, const unsigned int version);
1130
1131 private:
1132 /**
1133 * A structure that describes properties of the base tensor.
1134 */
1135 using base_tensor_descriptor =
1136 internal::SymmetricTensorAccessors::StorageType<rank_, dim, Number>;
1137
1138 /**
1139 * Data storage type for a symmetric tensor.
1140 */
1141 using base_tensor_type = typename base_tensor_descriptor::base_tensor_type;
1142
1143 /**
1144 * The place where we store the data of the tensor.
1145 */
1146 base_tensor_type data;
1147
1148 #ifndef DOXYGEN
1149
1150 // Make all other symmetric tensors friends.
1151 template <int, int, typename>
1152 friend class SymmetricTensor;
1153
1154 // Make a few more functions friends.
1155 template <int dim2, typename Number2>
1156 friend DEAL_II_HOST constexpr Number2
1157 trace(const SymmetricTensor<2, dim2, Number2> &d);
1158
1159 template <int dim2, typename Number2>
1160 friend DEAL_II_HOST DEAL_II_CONSTEXPR Number2
1161 determinant(const SymmetricTensor<2, dim2, Number2> &t);
1162
1163 template <int dim2, typename Number2>
1164 friend DEAL_II_HOST constexpr SymmetricTensor<2, dim2, Number2>
1165 deviator(const SymmetricTensor<2, dim2, Number2> &t);
1166
1167 template <int dim2, typename Number2>
1168 friend DEAL_II_HOST DEAL_II_CONSTEXPR SymmetricTensor<2, dim2, Number2>
1169 unit_symmetric_tensor();
1170
1171 template <int dim2, typename Number2>
1172 friend DEAL_II_HOST DEAL_II_CONSTEXPR SymmetricTensor<4, dim2, Number2>
1173 deviator_tensor();
1174
1175 template <int dim2, typename Number2>
1176 friend DEAL_II_HOST DEAL_II_CONSTEXPR SymmetricTensor<4, dim2, Number2>
1177 identity_tensor();
1178
1179
1180 // Make a few helper classes friends as well.
1181 friend struct internal::SymmetricTensorImplementation::
1182 Inverse<2, dim, Number>;
1183
1184 friend struct internal::SymmetricTensorImplementation::
1185 Inverse<4, dim, Number>;
1186 #endif
1187 };
1188
1189
1190
1191 // ------------------------- inline functions ------------------------
1192
1193 #ifndef DOXYGEN
1194
1195 // provide declarations for static members
1196 template <int rank, int dim, typename Number>
1197 const unsigned int SymmetricTensor<rank, dim, Number>::dimension;
1198
1199 template <int rank_, int dim, typename Number>
1200 constexpr unsigned int
1201 SymmetricTensor<rank_, dim, Number>::n_independent_components;
1202
1203 namespace internal
1204 {
1205 namespace SymmetricTensorAccessors
1206 {
1207 template <int rank_, int dim, bool constness, int P, typename Number>
1208 DEAL_II_HOST constexpr DEAL_II_ALWAYS_INLINE
1209 Accessor<rank_, dim, constness, P, Number>::Accessor(
1210 tensor_type &tensor,
1211 const TableIndices<rank_> &previous_indices)
1212 : tensor(tensor)
1213 , previous_indices(previous_indices)
1214 {}
1215
1216
1217
1218 template <int rank_, int dim, bool constness, int P, typename Number>
1219 DEAL_II_HOST constexpr inline DEAL_II_ALWAYS_INLINE
1220 Accessor<rank_, dim, constness, P - 1, Number>
1221 Accessor<rank_, dim, constness, P, Number>::operator[](
1222 const unsigned int i)
1223 {
1224 return Accessor<rank_, dim, constness, P - 1, Number>(
1225 tensor, merge(previous_indices, i, rank_ - P));
1226 }
1227
1228
1229
1230 template <int rank_, int dim, bool constness, int P, typename Number>
1231 DEAL_II_HOST constexpr DEAL_II_ALWAYS_INLINE
1232 Accessor<rank_, dim, constness, P - 1, Number>
1233 Accessor<rank_, dim, constness, P, Number>::operator[](
1234 const unsigned int i) const
1235 {
1236 return Accessor<rank_, dim, constness, P - 1, Number>(
1237 tensor, merge(previous_indices, i, rank_ - P));
1238 }
1239
1240
1241
1242 template <int rank_, int dim, bool constness, typename Number>
1243 DEAL_II_HOST constexpr DEAL_II_ALWAYS_INLINE
1244 Accessor<rank_, dim, constness, 1, Number>::Accessor(
1245 tensor_type &tensor,
1246 const TableIndices<rank_> &previous_indices)
1247 : tensor(tensor)
1248 , previous_indices(previous_indices)
1249 {}
1250
1251
1252
1253 template <int rank_, int dim, bool constness, typename Number>
1254 DEAL_II_HOST constexpr inline DEAL_II_ALWAYS_INLINE
1255 typename Accessor<rank_, dim, constness, 1, Number>::reference
1256 Accessor<rank_, dim, constness, 1, Number>::operator[](
1257 const unsigned int i)
1258 {
1259 return tensor(merge(previous_indices, i, rank_ - 1));
1260 }
1261
1262
1263 template <int rank_, int dim, bool constness, typename Number>
1264 DEAL_II_HOST constexpr DEAL_II_ALWAYS_INLINE
1265 typename Accessor<rank_, dim, constness, 1, Number>::reference
1266 Accessor<rank_, dim, constness, 1, Number>::operator[](
1267 const unsigned int i) const
1268 {
1269 return tensor(merge(previous_indices, i, rank_ - 1));
1270 }
1271 } // namespace SymmetricTensorAccessors
1272 } // namespace internal
1273
1274
1275
1276 template <int rank_, int dim, typename Number>
1277 template <typename OtherNumber>
1278 inline DEAL_II_ALWAYS_INLINE
1279 SymmetricTensor<rank_, dim, Number>::SymmetricTensor(
1280 const Tensor<2, dim, OtherNumber> &t)
1281 {
1282 static_assert(rank == 2, "This function is only implemented for rank==2");
1283 for (unsigned int d = 0; d < dim; ++d)
1284 for (unsigned int e = 0; e < d; ++e)
1285 Assert(t[d][e] == t[e][d],
1286 ExcMessage("The incoming Tensor must be exactly symmetric."));
1287
1288 for (unsigned int d = 0; d < dim; ++d)
1289 data[d] = t[d][d];
1290
1291 for (unsigned int d = 0, c = 0; d < dim; ++d)
1292 for (unsigned int e = d + 1; e < dim; ++e, ++c)
1293 data[dim + c] = t[d][e];
1294 }
1295
1296
1297
1298 template <int rank_, int dim, typename Number>
1299 template <typename OtherNumber>
1300 DEAL_II_HOST constexpr DEAL_II_ALWAYS_INLINE
1301 SymmetricTensor<rank_, dim, Number>::SymmetricTensor(
1302 const SymmetricTensor<rank_, dim, OtherNumber> &initializer)
1303 : data(initializer.data)
1304 {}
1305
1306
1307
1308 template <int rank_, int dim, typename Number>
1309 DEAL_II_HOST constexpr inline DEAL_II_ALWAYS_INLINE
1310 SymmetricTensor<rank_, dim, Number>::SymmetricTensor(
1311 const Number (&array)[n_independent_components])
1312 : data(
1313 *reinterpret_cast<const typename base_tensor_type::array_type *>(array))
1314 {
1315 // ensure that the reinterpret_cast above actually works
1316 Assert(sizeof(typename base_tensor_type::array_type) == sizeof(array),
1317 ExcInternalError());
1318 }
1319
1320
1321
1322 template <int rank_, int dim, typename Number>
1323 template <typename OtherNumber>
1324 DEAL_II_HOST constexpr inline DEAL_II_ALWAYS_INLINE
1325 SymmetricTensor<rank_, dim, Number> &
1326 SymmetricTensor<rank_, dim, Number>::operator=(
1327 const SymmetricTensor<rank_, dim, OtherNumber> &t)
1328 {
1329 data = t.data;
1330 return *this;
1331 }
1332
1333
1334
1335 template <int rank_, int dim, typename Number>
1336 DEAL_II_HOST constexpr inline DEAL_II_ALWAYS_INLINE
1337 SymmetricTensor<rank_, dim, Number> &
1338 SymmetricTensor<rank_, dim, Number>::operator=(const Number &d)
1339 {
1340 Assert(numbers::value_is_zero(d),
1341 ExcMessage("Only assignment with zero is allowed"));
1342 (void)d;
1343
1344 data = internal::NumberType<Number>::value(0.0);
1345
1346 return *this;
1347 }
1348
1349
1350 namespace internal
1351 {
1352 namespace SymmetricTensorImplementation
1353 {
1354 template <int dim, typename Number>
1355 constexpr inline DEAL_II_ALWAYS_INLINE dealii::Tensor<2, dim, Number>
1356 convert_to_tensor(const dealii::SymmetricTensor<2, dim, Number> &s)
1357 {
1358 dealii::Tensor<2, dim, Number> t;
1359
1360 // diagonal entries are stored first
1361 for (unsigned int d = 0; d < dim; ++d)
1362 t[d][d] = s.access_raw_entry(d);
1363
1364 // off-diagonal entries come next, row by row
1365 for (unsigned int d = 0, c = 0; d < dim; ++d)
1366 for (unsigned int e = d + 1; e < dim; ++e, ++c)
1367 {
1368 t[d][e] = s.access_raw_entry(dim + c);
1369 t[e][d] = s.access_raw_entry(dim + c);
1370 }
1371 return t;
1372 }
1373
1374
1375 template <int dim, typename Number>
1376 constexpr dealii::Tensor<4, dim, Number>
1377 convert_to_tensor(const dealii::SymmetricTensor<4, dim, Number> &st)
1378 {
1379 // utilize the symmetry properties of SymmetricTensor<4,dim>
1380 // discussed in the class documentation to avoid accessing all
1381 // independent elements of the input tensor more than once
1382 dealii::Tensor<4, dim, Number> t;
1383
1384 for (unsigned int i = 0; i < dim; ++i)
1385 for (unsigned int j = i; j < dim; ++j)
1386 for (unsigned int k = 0; k < dim; ++k)
1387 for (unsigned int l = k; l < dim; ++l)
1388 t[TableIndices<4>(i, j, k, l)] = t[TableIndices<4>(i, j, l, k)] =
1389 t[TableIndices<4>(j, i, k, l)] =
1390 t[TableIndices<4>(j, i, l, k)] =
1391 st[TableIndices<4>(i, j, k, l)];
1392
1393 return t;
1394 }
1395
1396
1397 template <typename Number>
1398 struct Inverse<2, 1, Number>
1399 {
1400 constexpr static inline DEAL_II_ALWAYS_INLINE
1401 dealii::SymmetricTensor<2, 1, Number>
1402 value(const dealii::SymmetricTensor<2, 1, Number> &t)
1403 {
1404 dealii::SymmetricTensor<2, 1, Number> tmp;
1405
1406 tmp[0][0] = 1.0 / t[0][0];
1407
1408 return tmp;
1409 }
1410 };
1411
1412
1413 template <typename Number>
1414 struct Inverse<2, 2, Number>
1415 {
1416 constexpr static inline DEAL_II_ALWAYS_INLINE
1417 dealii::SymmetricTensor<2, 2, Number>
1418 value(const dealii::SymmetricTensor<2, 2, Number> &t)
1419 {
1420 dealii::SymmetricTensor<2, 2, Number> tmp;
1421
1422 // Sympy result: ([
1423 // [ t11/(t00*t11 - t01**2), -t01/(t00*t11 - t01**2)],
1424 // [-t01/(t00*t11 - t01**2), t00/(t00*t11 - t01**2)] ])
1425 const TableIndices<2> idx_00(0, 0);
1426 const TableIndices<2> idx_01(0, 1);
1427 const TableIndices<2> idx_11(1, 1);
1428 const Number inv_det_t =
1429 1.0 / (t[idx_00] * t[idx_11] - t[idx_01] * t[idx_01]);
1430 tmp[idx_00] = t[idx_11];
1431 tmp[idx_01] = -t[idx_01];
1432 tmp[idx_11] = t[idx_00];
1433 tmp *= inv_det_t;
1434
1435 return tmp;
1436 }
1437 };
1438
1439
1440 template <typename Number>
1441 struct Inverse<2, 3, Number>
1442 {
1443 constexpr static dealii::SymmetricTensor<2, 3, Number>
1444 value(const dealii::SymmetricTensor<2, 3, Number> &t)
1445 {
1446 dealii::SymmetricTensor<2, 3, Number> tmp;
1447
1448 // Sympy result: ([
1449 // [ (t11*t22 - t12**2)/(t00*t11*t22 - t00*t12**2 - t01**2*t22 +
1450 // 2*t01*t02*t12 - t02**2*t11),
1451 // (-t01*t22 + t02*t12)/(t00*t11*t22 - t00*t12**2 - t01**2*t22 +
1452 // 2*t01*t02*t12 - t02**2*t11),
1453 // (t01*t12 - t02*t11)/(t00*t11*t22 - t00*t12**2 - t01**2*t22 +
1454 // 2*t01*t02*t12 - t02**2*t11)],
1455 // [ (-t01*t22 + t02*t12)/(t00*t11*t22 - t00*t12**2 - t01**2*t22 +
1456 // 2*t01*t02*t12 - t02**2*t11),
1457 // (t00*t22 - t02**2)/(t00*t11*t22 - t00*t12**2 - t01**2*t22 +
1458 // 2*t01*t02*t12 - t02**2*t11),
1459 // (t00*t12 - t01*t02)/(-t00*t11*t22 + t00*t12**2 + t01**2*t22 -
1460 // 2*t01*t02*t12 + t02**2*t11)],
1461 // [ (t01*t12 - t02*t11)/(t00*t11*t22 - t00*t12**2 - t01**2*t22 +
1462 // 2*t01*t02*t12 - t02**2*t11),
1463 // (t00*t12 - t01*t02)/(-t00*t11*t22 + t00*t12**2 + t01**2*t22 -
1464 // 2*t01*t02*t12 + t02**2*t11),
1465 // (-t00*t11 + t01**2)/(-t00*t11*t22 + t00*t12**2 + t01**2*t22 -
1466 // 2*t01*t02*t12 + t02**2*t11)] ])
1467 //
1468 // =
1469 //
1470 // [ (t11*t22 - t12**2)/det_t,
1471 // (-t01*t22 + t02*t12)/det_t,
1472 // (t01*t12 - t02*t11)/det_t],
1473 // [ (-t01*t22 + t02*t12)/det_t,
1474 // (t00*t22 - t02**2)/det_t,
1475 // (-t00*t12 + t01*t02)/det_t],
1476 // [ (t01*t12 - t02*t11)/det_t,
1477 // (-t00*t12 + t01*t02)/det_t,
1478 // (t00*t11 - t01**2)/det_t] ])
1479 //
1480 // with det_t = (t00*t11*t22 - t00*t12**2 - t01**2*t22 +
1481 // 2*t01*t02*t12 - t02**2*t11)
1482 const TableIndices<2> idx_00(0, 0);
1483 const TableIndices<2> idx_01(0, 1);
1484 const TableIndices<2> idx_02(0, 2);
1485 const TableIndices<2> idx_11(1, 1);
1486 const TableIndices<2> idx_12(1, 2);
1487 const TableIndices<2> idx_22(2, 2);
1488 const Number inv_det_t =
1489 1.0 / (t[idx_00] * t[idx_11] * t[idx_22] -
1490 t[idx_00] * t[idx_12] * t[idx_12] -
1491 t[idx_01] * t[idx_01] * t[idx_22] +
1492 2.0 * t[idx_01] * t[idx_02] * t[idx_12] -
1493 t[idx_02] * t[idx_02] * t[idx_11]);
1494 tmp[idx_00] = t[idx_11] * t[idx_22] - t[idx_12] * t[idx_12];
1495 tmp[idx_01] = -t[idx_01] * t[idx_22] + t[idx_02] * t[idx_12];
1496 tmp[idx_02] = t[idx_01] * t[idx_12] - t[idx_02] * t[idx_11];
1497 tmp[idx_11] = t[idx_00] * t[idx_22] - t[idx_02] * t[idx_02];
1498 tmp[idx_12] = -t[idx_00] * t[idx_12] + t[idx_01] * t[idx_02];
1499 tmp[idx_22] = t[idx_00] * t[idx_11] - t[idx_01] * t[idx_01];
1500 tmp *= inv_det_t;
1501
1502 return tmp;
1503 }
1504 };
1505
1506
1507 template <typename Number>
1508 struct Inverse<4, 1, Number>
1509 {
1510 constexpr static inline dealii::SymmetricTensor<4, 1, Number>
1511 value(const dealii::SymmetricTensor<4, 1, Number> &t)
1512 {
1513 dealii::SymmetricTensor<4, 1, Number> tmp;
1514 tmp.data[0][0] = 1.0 / t.data[0][0];
1515 return tmp;
1516 }
1517 };
1518
1519
1520 template <typename Number>
1521 struct Inverse<4, 2, Number>
1522 {
1523 constexpr static inline dealii::SymmetricTensor<4, 2, Number>
1524 value(const dealii::SymmetricTensor<4, 2, Number> &t)
1525 {
1526 dealii::SymmetricTensor<4, 2, Number> tmp;
1527
1528 // Inverting this tensor is a little more complicated than necessary,
1529 // since we store the data of 't' as a 3x3 matrix t.data, but the
1530 // product between a rank-4 and a rank-2 tensor is really not the
1531 // product between this matrix and the 3-vector of a rhs, but rather
1532 //
1533 // B.vec = t.data * mult * A.vec
1534 //
1535 // where mult is a 3x3 matrix with entries [[1,0,0],[0,1,0],[0,0,2]] to
1536 // capture the fact that we need to add up both the c_ij12*a_12 and the
1537 // c_ij21*a_21 terms.
1538 //
1539 // In addition, in this scheme, the identity tensor has the matrix
1540 // representation mult^-1.
1541 //
1542 // The inverse of 't' therefore has the matrix representation
1543 //
1544 // inv.data = mult^-1 * t.data^-1 * mult^-1
1545 //
1546 // in order to compute it, let's first compute the inverse of t.data and
1547 // put it into tmp.data; at the end of the function we then scale the
1548 // last row and column of the inverse by 1/2, corresponding to the left
1549 // and right multiplication with mult^-1.
1550 const Number t4 = t.data[0][0] * t.data[1][1],
1551 t6 = t.data[0][0] * t.data[1][2],
1552 t8 = t.data[0][1] * t.data[1][0],
1553 t00 = t.data[0][2] * t.data[1][0],
1554 t01 = t.data[0][1] * t.data[2][0],
1555 t04 = t.data[0][2] * t.data[2][0],
1556 t07 = 1.0 / (t4 * t.data[2][2] - t6 * t.data[2][1] -
1557 t8 * t.data[2][2] + t00 * t.data[2][1] +
1558 t01 * t.data[1][2] - t04 * t.data[1][1]);
1559 tmp.data[0][0] =
1560 (t.data[1][1] * t.data[2][2] - t.data[1][2] * t.data[2][1]) * t07;
1561 tmp.data[0][1] =
1562 -(t.data[0][1] * t.data[2][2] - t.data[0][2] * t.data[2][1]) * t07;
1563 tmp.data[0][2] =
1564 -(-t.data[0][1] * t.data[1][2] + t.data[0][2] * t.data[1][1]) * t07;
1565 tmp.data[1][0] =
1566 -(t.data[1][0] * t.data[2][2] - t.data[1][2] * t.data[2][0]) * t07;
1567 tmp.data[1][1] = (t.data[0][0] * t.data[2][2] - t04) * t07;
1568 tmp.data[1][2] = -(t6 - t00) * t07;
1569 tmp.data[2][0] =
1570 -(-t.data[1][0] * t.data[2][1] + t.data[1][1] * t.data[2][0]) * t07;
1571 tmp.data[2][1] = -(t.data[0][0] * t.data[2][1] - t01) * t07;
1572 tmp.data[2][2] = (t4 - t8) * t07;
1573
1574 // scale last row and column as mentioned
1575 // above
1576 tmp.data[2][0] /= 2;
1577 tmp.data[2][1] /= 2;
1578 tmp.data[0][2] /= 2;
1579 tmp.data[1][2] /= 2;
1580 tmp.data[2][2] /= 4;
1581
1582 return tmp;
1583 }
1584 };
1585
1586
1587 template <typename Number>
1588 struct Inverse<4, 3, Number>
1589 {
1590 static dealii::SymmetricTensor<4, 3, Number>
1591 value(const dealii::SymmetricTensor<4, 3, Number> &t)
1592 {
1593 dealii::SymmetricTensor<4, 3, Number> tmp = t;
1594
1595 // This function follows the exact same scheme as the 2d case, except
1596 // that hardcoding the inverse of a 6x6 matrix is pretty wasteful.
1597 // Instead, we use the Gauss-Jordan algorithm implemented for
1598 // FullMatrix. For historical reasons the following code is copied from
1599 // there, with the tangential benefit that we do not need to copy the
1600 // tensor entries to and from the FullMatrix.
1601 const unsigned int N = 6;
1602
1603 // First get an estimate of the size of the elements of this matrix,
1604 // for later checks whether the pivot element is large enough, or
1605 // whether we have to fear that the matrix is not regular.
1606 Number diagonal_sum = internal::NumberType<Number>::value(0.0);
1607 for (unsigned int i = 0; i < N; ++i)
1608 diagonal_sum += numbers::NumberTraits<Number>::abs(tmp.data[i][i]);
1609 const Number typical_diagonal_element =
1610 diagonal_sum / static_cast<double>(N);
1611 (void)typical_diagonal_element;
1612
1613 unsigned int p[N];
1614 for (unsigned int i = 0; i < N; ++i)
1615 p[i] = i;
1616
1617 for (unsigned int j = 0; j < N; ++j)
1618 {
1619 // Pivot search: search that part of the line on and right of the
1620 // diagonal for the largest element.
1621 Number max = numbers::NumberTraits<Number>::abs(tmp.data[j][j]);
1622 unsigned int r = j;
1623 for (unsigned int i = j + 1; i < N; ++i)
1624 if (numbers::NumberTraits<Number>::abs(tmp.data[i][j]) > max)
1625 {
1626 max = numbers::NumberTraits<Number>::abs(tmp.data[i][j]);
1627 r = i;
1628 }
1629
1630 // Check whether the pivot is too small
1631 Assert(max > 1.e-16 * typical_diagonal_element,
1632 ExcMessage("This tensor seems to be noninvertible"));
1633
1634 // Row interchange
1635 if (r > j)
1636 {
1637 for (unsigned int k = 0; k < N; ++k)
1638 std::swap(tmp.data[j][k], tmp.data[r][k]);
1639
1640 std::swap(p[j], p[r]);
1641 }
1642
1643 // Transformation
1644 const Number hr = 1. / tmp.data[j][j];
1645 tmp.data[j][j] = hr;
1646 for (unsigned int k = 0; k < N; ++k)
1647 {
1648 if (k == j)
1649 continue;
1650 for (unsigned int i = 0; i < N; ++i)
1651 {
1652 if (i == j)
1653 continue;
1654 tmp.data[i][k] -= tmp.data[i][j] * tmp.data[j][k] * hr;
1655 }
1656 }
1657 for (unsigned int i = 0; i < N; ++i)
1658 {
1659 tmp.data[i][j] *= hr;
1660 tmp.data[j][i] *= -hr;
1661 }
1662 tmp.data[j][j] = hr;
1663 }
1664
1665 // Column interchange
1666 Number hv[N];
1667 for (unsigned int i = 0; i < N; ++i)
1668 {
1669 for (unsigned int k = 0; k < N; ++k)
1670 hv[p[k]] = tmp.data[i][k];
1671 for (unsigned int k = 0; k < N; ++k)
1672 tmp.data[i][k] = hv[k];
1673 }
1674
1675 // Scale rows and columns. The mult matrix
1676 // here is diag[1, 1, 1, 1/2, 1/2, 1/2].
1677 for (unsigned int i = 3; i < 6; ++i)
1678 for (unsigned int j = 0; j < 3; ++j)
1679 tmp.data[i][j] /= 2;
1680
1681 for (unsigned int i = 0; i < 3; ++i)
1682 for (unsigned int j = 3; j < 6; ++j)
1683 tmp.data[i][j] /= 2;
1684
1685 for (unsigned int i = 3; i < 6; ++i)
1686 for (unsigned int j = 3; j < 6; ++j)
1687 tmp.data[i][j] /= 4;
1688
1689 return tmp;
1690 }
1691 };
1692
1693 } // namespace SymmetricTensorImplementation
1694 } // namespace internal
1695
1696
1697
1698 template <int rank_, int dim, typename Number>
1699 DEAL_II_HOST constexpr DEAL_II_ALWAYS_INLINE
1700 SymmetricTensor<rank_, dim, Number>::operator Tensor<rank_, dim, Number>()
1701 const
1702 {
1703 return internal::SymmetricTensorImplementation::convert_to_tensor(*this);
1704 }
1705
1706
1707
1708 template <int rank_, int dim, typename Number>
1709 DEAL_II_HOST constexpr bool
1710 SymmetricTensor<rank_, dim, Number>::operator==(
1711 const SymmetricTensor<rank_, dim, Number> &t) const
1712 {
1713 return data == t.data;
1714 }
1715
1716
1717
1718 template <int rank_, int dim, typename Number>
1719 DEAL_II_HOST constexpr bool
1720 SymmetricTensor<rank_, dim, Number>::operator!=(
1721 const SymmetricTensor<rank_, dim, Number> &t) const
1722 {
1723 return data != t.data;
1724 }
1725
1726
1727
1728 template <int rank_, int dim, typename Number>
1729 template <typename OtherNumber>
1730 DEAL_II_HOST constexpr inline DEAL_II_ALWAYS_INLINE
1731 SymmetricTensor<rank_, dim, Number> &
1732 SymmetricTensor<rank_, dim, Number>::operator+=(
1733 const SymmetricTensor<rank_, dim, OtherNumber> &t)
1734 {
1735 data += t.data;
1736 return *this;
1737 }
1738
1739
1740
1741 template <int rank_, int dim, typename Number>
1742 template <typename OtherNumber>
1743 DEAL_II_HOST constexpr inline DEAL_II_ALWAYS_INLINE
1744 SymmetricTensor<rank_, dim, Number> &
1745 SymmetricTensor<rank_, dim, Number>::operator-=(
1746 const SymmetricTensor<rank_, dim, OtherNumber> &t)
1747 {
1748 data -= t.data;
1749 return *this;
1750 }
1751
1752
1753
1754 template <int rank_, int dim, typename Number>
1755 template <typename OtherNumber>
1756 DEAL_II_HOST constexpr inline DEAL_II_ALWAYS_INLINE
1757 SymmetricTensor<rank_, dim, Number> &
1758 SymmetricTensor<rank_, dim, Number>::operator*=(const OtherNumber &d)
1759 {
1760 data *= d;
1761 return *this;
1762 }
1763
1764
1765
1766 template <int rank_, int dim, typename Number>
1767 template <typename OtherNumber>
1768 DEAL_II_HOST constexpr inline DEAL_II_ALWAYS_INLINE
1769 SymmetricTensor<rank_, dim, Number> &
1770 SymmetricTensor<rank_, dim, Number>::operator/=(const OtherNumber &d)
1771 {
1772 data /= d;
1773 return *this;
1774 }
1775
1776
1777
1778 template <int rank_, int dim, typename Number>
1779 DEAL_II_HOST constexpr inline DEAL_II_ALWAYS_INLINE
1780 SymmetricTensor<rank_, dim, Number>
1781 SymmetricTensor<rank_, dim, Number>::operator-() const
1782 {
1783 SymmetricTensor tmp = *this;
1784 tmp.data = -tmp.data;
1785 return tmp;
1786 }
1787
1788
1789
1790 template <int rank_, int dim, typename Number>
1791 DEAL_II_HOST constexpr inline DEAL_II_ALWAYS_INLINE void
1792 SymmetricTensor<rank_, dim, Number>::clear()
1793 {
1794 data.clear();
1795 }
1796
1797
1798
1799 template <int rank_, int dim, typename Number>
1800 DEAL_II_HOST constexpr std::size_t
1801 SymmetricTensor<rank_, dim, Number>::memory_consumption()
1802 {
1803 // all memory consists of statically allocated memory of the current
1804 // object, no pointers
1805 return sizeof(SymmetricTensor<rank_, dim, Number>);
1806 }
1807
1808
1809
1810 namespace internal
1811 {
1812 /**
1813 * Perform the double contraction between two rank-2 symmetric tensors.
1814 */
1815 template <int dim, typename Number, typename OtherNumber = Number>
1816 DEAL_II_HOST DEAL_II_CONSTEXPR inline DEAL_II_ALWAYS_INLINE
1817 typename SymmetricTensorAccessors::
1818 double_contraction_result<2, 2, dim, Number, OtherNumber>::type
1819 perform_double_contraction(
1820 const typename SymmetricTensorAccessors::StorageType<2, dim, Number>::
1821 base_tensor_type &data,
1822 const typename SymmetricTensorAccessors::
1823 StorageType<2, dim, OtherNumber>::base_tensor_type &sdata)
1824 {
1825 using result_type = typename SymmetricTensorAccessors::
1826 double_contraction_result<2, 2, dim, Number, OtherNumber>::type;
1827
1828 switch (dim)
1829 {
1830 case 1:
1831 return data[0] * sdata[0];
1832
1833 default:
1834 // Start with the non-diagonal part. These values appear
1835 // twice in the matrix, but are only stored once. So we can
1836 // get the double-contraction sum for these elements using
1837 // only one multiplication each, and at the end multiplying
1838 // things by 2.
1839 result_type sum = data[dim] * sdata[dim];
1840 for (unsigned int d = dim + 1; d < (dim * (dim + 1) / 2); ++d)
1841 sum += data[d] * sdata[d];
1842 sum += sum; // sum *= 2
1843
1844 // Now add the contributions from the diagonal
1845 for (unsigned int d = 0; d < dim; ++d)
1846 sum += data[d] * sdata[d];
1847 return sum;
1848 }
1849 }
1850
1851
1852
1853 /**
1854 * Perform the double contraction between a rank-4 and a rank-2
1855 * symmetric tensor.
1856 */
1857 template <int dim, typename Number, typename OtherNumber = Number>
1858 DEAL_II_HOST DEAL_II_CONSTEXPR inline DEAL_II_ALWAYS_INLINE
1859 typename SymmetricTensorAccessors::
1860 double_contraction_result<4, 2, dim, Number, OtherNumber>::type
1861 perform_double_contraction(
1862 const typename SymmetricTensorAccessors::StorageType<4, dim, Number>::
1863 base_tensor_type &data,
1864 const typename SymmetricTensorAccessors::
1865 StorageType<2, dim, OtherNumber>::base_tensor_type &sdata)
1866 {
1867 using result_type = typename SymmetricTensorAccessors::
1868 double_contraction_result<4, 2, dim, Number, OtherNumber>::type;
1869 using value_type = typename SymmetricTensorAccessors::
1870 double_contraction_result<4, 2, dim, Number, OtherNumber>::value_type;
1871
1872 const unsigned int data_dim = SymmetricTensorAccessors::
1873 StorageType<2, dim, value_type>::n_independent_components;
1874 value_type tmp[data_dim]{};
1875 for (unsigned int i = 0; i < data_dim; ++i)
1876 tmp[i] =
1877 perform_double_contraction<dim, Number, OtherNumber>(data[i], sdata);
1878 return result_type(tmp);
1879 }
1880
1881
1882
1883 /**
1884 * Perform the double contraction between a rank-2 and a rank-4
1885 * symmetric tensor.
1886 */
1887 template <int dim, typename Number, typename OtherNumber = Number>
1888 DEAL_II_HOST DEAL_II_CONSTEXPR inline DEAL_II_ALWAYS_INLINE
1889 typename SymmetricTensorAccessors::StorageType<
1890 2,
1891 dim,
1892 typename SymmetricTensorAccessors::
1893 double_contraction_result<2, 4, dim, Number, OtherNumber>::value_type>::
1894 base_tensor_type
1895 perform_double_contraction(
1896 const typename SymmetricTensorAccessors::StorageType<2, dim, Number>::
1897 base_tensor_type &data,
1898 const typename SymmetricTensorAccessors::
1899 StorageType<4, dim, OtherNumber>::base_tensor_type &sdata)
1900 {
1901 using value_type = typename SymmetricTensorAccessors::
1902 double_contraction_result<2, 4, dim, Number, OtherNumber>::value_type;
1903 using base_tensor_type = typename SymmetricTensorAccessors::
1904 StorageType<2, dim, value_type>::base_tensor_type;
1905
1906 base_tensor_type tmp;
1907 for (unsigned int i = 0; i < tmp.dimension; ++i)
1908 {
1909 // Start with the non-diagonal part. These values appear
1910 // twice in the matrix, but are only stored once. So we can
1911 // get the double-contraction sum for these elements using
1912 // only one multiplication each, and at the end multiplying
1913 // things by 2.
1914 value_type sum = data[dim] * sdata[dim][i];
1915 for (unsigned int d = dim + 1; d < (dim * (dim + 1) / 2); ++d)
1916 sum += data[d] * sdata[d][i];
1917 sum += sum; // sum *= 2
1918
1919 // Now add the contributions from the diagonal
1920 for (unsigned int d = 0; d < dim; ++d)
1921 sum += data[d] * sdata[d][i];
1922 tmp[i] = sum;
1923 }
1924 return tmp;
1925 }
1926
1927
1928
1929 /**
1930 * Perform the double contraction between two rank-4 symmetric tensors.
1931 */
1932 template <int dim, typename Number, typename OtherNumber = Number>
1933 DEAL_II_HOST DEAL_II_CONSTEXPR inline DEAL_II_ALWAYS_INLINE
1934 typename SymmetricTensorAccessors::StorageType<
1935 4,
1936 dim,
1937 typename SymmetricTensorAccessors::
1938 double_contraction_result<4, 4, dim, Number, OtherNumber>::value_type>::
1939 base_tensor_type
1940 perform_double_contraction(
1941 const typename SymmetricTensorAccessors::StorageType<4, dim, Number>::
1942 base_tensor_type &data,
1943 const typename SymmetricTensorAccessors::
1944 StorageType<4, dim, OtherNumber>::base_tensor_type &sdata)
1945 {
1946 using value_type = typename SymmetricTensorAccessors::
1947 double_contraction_result<4, 4, dim, Number, OtherNumber>::value_type;
1948 using base_tensor_type = typename SymmetricTensorAccessors::
1949 StorageType<4, dim, value_type>::base_tensor_type;
1950
1951 const unsigned int data_dim = SymmetricTensorAccessors::
1952 StorageType<2, dim, value_type>::n_independent_components;
1953 base_tensor_type tmp;
1954 for (unsigned int i = 0; i < data_dim; ++i)
1955 for (unsigned int j = 0; j < data_dim; ++j)
1956 {
1957 // Start with the non-diagonal part
1958 for (unsigned int d = dim; d < (dim * (dim + 1) / 2); ++d)
1959 tmp[i][j] += data[i][d] * sdata[d][j];
1960 tmp[i][j] += tmp[i][j]; // tmp[i][j] *= 2;
1961
1962 // Now add the contributions from the diagonal
1963 for (unsigned int d = 0; d < dim; ++d)
1964 tmp[i][j] += data[i][d] * sdata[d][j];
1965 }
1966 return tmp;
1967 }
1968
1969 } // end of namespace internal
1970
1971
1972
1973 template <int rank_, int dim, typename Number>
1974 template <typename OtherNumber>
1975 DEAL_II_HOST DEAL_II_CONSTEXPR inline DEAL_II_ALWAYS_INLINE
1976 typename internal::SymmetricTensorAccessors::
1977 double_contraction_result<rank_, 2, dim, Number, OtherNumber>::type
1978 SymmetricTensor<rank_, dim, Number>::operator*(
1979 const SymmetricTensor<2, dim, OtherNumber> &s) const
1980 {
1981 // Dispatch to functions that know the types of the involved
1982 // arguments via overloads.
1983 return internal::perform_double_contraction<dim, Number, OtherNumber>(data,
1984 s.data);
1985 }
1986
1987
1988
1989 template <int rank_, int dim, typename Number>
1990 template <typename OtherNumber>
1991 DEAL_II_HOST DEAL_II_CONSTEXPR inline
1992 typename internal::SymmetricTensorAccessors::
1993 double_contraction_result<rank_, 4, dim, Number, OtherNumber>::type
1994 SymmetricTensor<rank_, dim, Number>::operator*(
1995 const SymmetricTensor<4, dim, OtherNumber> &s) const
1996 {
1997 typename internal::SymmetricTensorAccessors::
1998 double_contraction_result<rank_, 4, dim, Number, OtherNumber>::type tmp;
1999 tmp.data =
2000 internal::perform_double_contraction<dim, Number, OtherNumber>(data,
2001 s.data);
2002 return tmp;
2003 }
2004
2005
2006
2007 // internal namespace to switch between the
2008 // access of different tensors. There used to
2009 // be explicit instantiations before for
2010 // different ranks and dimensions, but since
2011 // we now allow for templates on the data
2012 // type, and since we cannot partially
2013 // specialize the implementation, this got
2014 // into a separate namespace
2015 namespace internal
2016 {
2017 namespace SymmetricTensorImplementation
2018 {
2019 // a function to do the unrolling from a set of indices to a
2020 // scalar index into the array in which we store the elements of
2021 // a symmetric tensor
2022 //
2023 // this function is for rank-2 tensors
2024 template <int dim>
2025 constexpr inline DEAL_II_ALWAYS_INLINE unsigned int
2026 component_to_unrolled_index(const TableIndices<2> &indices)
2027 {
2028 AssertIndexRange(indices[0], dim);
2029 AssertIndexRange(indices[1], dim);
2030
2031 switch (dim)
2032 {
2033 case 1:
2034 {
2035 return 0;
2036 }
2037 case 2:
2038 {
2039 constexpr dealii::ndarray<unsigned int, 2, 2> table = {
2040 {{{0, 2}}, {{2, 1}}}};
2041 return table[indices[0]][indices[1]];
2042 }
2043 case 3:
2044 {
2045 constexpr dealii::ndarray<unsigned int, 3, 3> table = {
2046 {{{0, 3, 4}}, {{3, 1, 5}}, {{4, 5, 2}}}};
2047 return table[indices[0]][indices[1]];
2048 }
2049 case 4:
2050 {
2051 constexpr dealii::ndarray<unsigned int, 4, 4> table = {
2052 {{{0, 4, 5, 6}},
2053 {{4, 1, 7, 8}},
2054 {{5, 7, 2, 9}},
2055 {{6, 8, 9, 3}}}};
2056 return table[indices[0]][indices[1]];
2057 }
2058 default:
2059 // for the remainder, manually figure out the numbering
2060 {
2061 if (indices[0] == indices[1])
2062 return indices[0];
2063
2064 const TableIndices<2> sorted_indices(
2065 std::min(indices[0], indices[1]),
2066 std::max(indices[0], indices[1]));
2067
2068 // Here (d, e) are the row and column of the symmetric matrix and
2069 // 'dim + c' is the index into the Tensor<1, dim> actually used
2070 // for storage.
2071 unsigned int c = 0;
2072 for (unsigned int d = 0; d < dim; ++d)
2073 for (unsigned int e = d + 1; e < dim; ++e, ++c)
2074 if ((sorted_indices[0] == d) && (sorted_indices[1] == e))
2075 return dim + c;
2076
2077 // should never get here:
2078 DEAL_II_ASSERT_UNREACHABLE();
2079 return 0;
2080 }
2081 }
2082 }
2083
2084 // a function to do the unrolling from a set of indices to a
2085 // scalar index into the array in which we store the elements of
2086 // a symmetric tensor
2087 //
2088 // this function is for tensors of ranks not already handled
2089 // above
2090 template <int dim, int rank_>
2091 constexpr inline unsigned int
2092 component_to_unrolled_index(const TableIndices<rank_> &indices)
2093 {
2094 (void)indices;
2095 DEAL_II_NOT_IMPLEMENTED();
2096 return numbers::invalid_unsigned_int;
2097 }
2098 } // namespace SymmetricTensorImplementation
2099
2100 template <int dim, typename Number>
2101 constexpr inline DEAL_II_ALWAYS_INLINE Number &
2102 symmetric_tensor_access(const TableIndices<2> &indices,
2103 typename SymmetricTensorAccessors::
2104 StorageType<2, dim, Number>::base_tensor_type &data)
2105 {
2106 return data[SymmetricTensorImplementation::component_to_unrolled_index<dim>(
2107 indices)];
2108 }
2109
2110
2111
2112 template <int dim, typename Number>
2113 constexpr inline DEAL_II_ALWAYS_INLINE const Number &
2114 symmetric_tensor_access(const TableIndices<2> &indices,
2115 const typename SymmetricTensorAccessors::
2116 StorageType<2, dim, Number>::base_tensor_type &data)
2117 {
2118 return data[SymmetricTensorImplementation::component_to_unrolled_index<dim>(
2119 indices)];
2120 }
2121
2122
2123
2124 template <int dim, typename Number>
2125 constexpr inline Number &
2126 symmetric_tensor_access(const TableIndices<4> &indices,
2127 typename SymmetricTensorAccessors::
2128 StorageType<4, dim, Number>::base_tensor_type &data)
2129 {
2130 switch (dim)
2131 {
2132 case 1:
2133 return data[0][0];
2134
2135 case 2:
2136 // each entry of the tensor can be thought of as an entry in a
2137 // matrix that maps the rolled-out rank-2 tensors into rolled-out
2138 // rank-2 tensors. this is the format in which we store rank-4
2139 // tensors. determine which position the present entry is
2140 // stored in
2141 {
2142 constexpr std::size_t base_index[2][2] = {{0, 2}, {2, 1}};
2143 return data[base_index[indices[0]][indices[1]]]
2144 [base_index[indices[2]][indices[3]]];
2145 }
2146 case 3:
2147 // each entry of the tensor can be thought of as an entry in a
2148 // matrix that maps the rolled-out rank-2 tensors into rolled-out
2149 // rank-2 tensors. this is the format in which we store rank-4
2150 // tensors. determine which position the present entry is
2151 // stored in
2152 {
2153 constexpr std::size_t base_index[3][3] = {{0, 3, 4},
2154 {3, 1, 5},
2155 {4, 5, 2}};
2156 return data[base_index[indices[0]][indices[1]]]
2157 [base_index[indices[2]][indices[3]]];
2158 }
2159
2160 default:
2161 DEAL_II_NOT_IMPLEMENTED();
2162 }
2163
2164 // The code should never reach here.
2165 // We cannot return a static variable, as this class must support number
2166 // types that require no instances of the number type to be in scope during
2167 // a reinitialization procedure (e.g. ADOL-C adtl::adouble).
2168 return data[0][0];
2169 }
2170
2171
2172 template <int dim, typename Number>
2173 constexpr inline DEAL_II_ALWAYS_INLINE const Number &
2174 symmetric_tensor_access(const TableIndices<4> &indices,
2175 const typename SymmetricTensorAccessors::
2176 StorageType<4, dim, Number>::base_tensor_type &data)
2177 {
2178 switch (dim)
2179 {
2180 case 1:
2181 return data[0][0];
2182
2183 case 2:
2184 // each entry of the tensor can be thought of as an entry in a
2185 // matrix that maps the rolled-out rank-2 tensors into rolled-out
2186 // rank-2 tensors. this is the format in which we store rank-4
2187 // tensors. determine which position the present entry is
2188 // stored in
2189 {
2190 constexpr std::size_t base_index[2][2] = {{0, 2}, {2, 1}};
2191 return data[base_index[indices[0]][indices[1]]]
2192 [base_index[indices[2]][indices[3]]];
2193 }
2194 case 3:
2195 // each entry of the tensor can be thought of as an entry in a
2196 // matrix that maps the rolled-out rank-2 tensors into rolled-out
2197 // rank-2 tensors. this is the format in which we store rank-4
2198 // tensors. determine which position the present entry is
2199 // stored in
2200 {
2201 constexpr std::size_t base_index[3][3] = {{0, 3, 4},
2202 {3, 1, 5},
2203 {4, 5, 2}};
2204 return data[base_index[indices[0]][indices[1]]]
2205 [base_index[indices[2]][indices[3]]];
2206 }
2207
2208 default:
2209 DEAL_II_NOT_IMPLEMENTED();
2210 }
2211
2212 // The code should never reach here.
2213 // We cannot return a static variable, as this class must support number
2214 // types that require no instances of the number type to be in scope during
2215 // a reinitialization procedure (e.g. ADOL-C adtl::adouble).
2216 return data[0][0];
2217 }
2218
2219 } // end of namespace internal
2220
2221
2222
2223 template <int rank_, int dim, typename Number>
2224 DEAL_II_HOST constexpr inline DEAL_II_ALWAYS_INLINE Number &
2225 SymmetricTensor<rank_, dim, Number>::operator()(
2226 const TableIndices<rank_> &indices)
2227 {
2228 for (unsigned int r = 0; r < rank; ++r)
2229 AssertIndexRange(indices[r], dimension);
2230 return internal::symmetric_tensor_access<dim, Number>(indices, data);
2231 }
2232
2233
2234
2235 template <int rank_, int dim, typename Number>
2236 DEAL_II_HOST constexpr inline DEAL_II_ALWAYS_INLINE const Number &
2237 SymmetricTensor<rank_, dim, Number>::operator()(
2238 const TableIndices<rank_> &indices) const
2239 {
2240 for (unsigned int r = 0; r < rank; ++r)
2241 AssertIndexRange(indices[r], dimension);
2242 return internal::symmetric_tensor_access<dim, Number>(indices, data);
2243 }
2244
2245
2246
2247 namespace internal
2248 {
2249 namespace SymmetricTensorImplementation
2250 {
2251 template <int rank_>
2252 constexpr TableIndices<rank_>
2253 get_partially_filled_indices(const unsigned int row,
2254 const std::integral_constant<int, 2> &)
2255 {
2256 return TableIndices<rank_>(row, numbers::invalid_unsigned_int);
2257 }
2258
2259
2260 template <int rank_>
2261 constexpr TableIndices<rank_>
2262 get_partially_filled_indices(const unsigned int row,
2263 const std::integral_constant<int, 4> &)
2264 {
2265 return TableIndices<rank_>(row,
2266 numbers::invalid_unsigned_int,
2267 numbers::invalid_unsigned_int,
2268 numbers::invalid_unsigned_int);
2269 }
2270 } // namespace SymmetricTensorImplementation
2271 } // namespace internal
2272
2273
2274 template <int rank_, int dim, typename Number>
2275 DEAL_II_HOST constexpr DEAL_II_ALWAYS_INLINE internal::
2276 SymmetricTensorAccessors::Accessor<rank_, dim, true, rank_ - 1, Number>
2277 SymmetricTensor<rank_, dim, Number>::operator[](const unsigned int row) const
2278 {
2279 return internal::SymmetricTensorAccessors::
2280 Accessor<rank_, dim, true, rank_ - 1, Number>(
2281 *this,
2282 internal::SymmetricTensorImplementation::get_partially_filled_indices<
2283 rank_>(row, std::integral_constant<int, rank_>()));
2284 }
2285
2286
2287
2288 template <int rank_, int dim, typename Number>
2289 DEAL_II_HOST constexpr inline DEAL_II_ALWAYS_INLINE internal::
2290 SymmetricTensorAccessors::Accessor<rank_, dim, false, rank_ - 1, Number>
2291 SymmetricTensor<rank_, dim, Number>::operator[](const unsigned int row)
2292 {
2293 return internal::SymmetricTensorAccessors::
2294 Accessor<rank_, dim, false, rank_ - 1, Number>(
2295 *this,
2296 internal::SymmetricTensorImplementation::get_partially_filled_indices<
2297 rank_>(row, std::integral_constant<int, rank_>()));
2298 }
2299
2300
2301
2302 template <int rank_, int dim, typename Number>
2303 DEAL_II_HOST constexpr DEAL_II_ALWAYS_INLINE const Number &
2304 SymmetricTensor<rank_, dim, Number>::operator[](
2305 const TableIndices<rank_> &indices) const
2306 {
2307 return operator()(indices);
2308 }
2309
2310
2311
2312 template <int rank_, int dim, typename Number>
2313 DEAL_II_HOST constexpr inline DEAL_II_ALWAYS_INLINE Number &
2314 SymmetricTensor<rank_, dim, Number>::operator[](
2315 const TableIndices<rank_> &indices)
2316 {
2317 return operator()(indices);
2318 }
2319
2320
2321
2322 template <int rank_, int dim, typename Number>
2323 DEAL_II_HOST constexpr inline const Number &
2324 SymmetricTensor<rank_, dim, Number>::access_raw_entry(
2325 const unsigned int index) const
2326 {
2327 AssertIndexRange(index, n_independent_components);
2328 if constexpr (rank == 2)
2329 return data[index];
2330 else
2331 return data[decltype(data)::unrolled_to_component_indices(index)];
2332 }
2333
2334
2335
2336 template <int rank_, int dim, typename Number>
2337 DEAL_II_HOST constexpr inline Number &
2338 SymmetricTensor<rank_, dim, Number>::access_raw_entry(const unsigned int index)
2339 {
2340 AssertIndexRange(index, n_independent_components);
2341 if constexpr (rank == 2)
2342 return data[index];
2343 else
2344 return data[decltype(data)::unrolled_to_component_indices(index)];
2345 }
2346
2347
2348
2349 namespace internal
2350 {
2351 template <int dim, typename Number>
2352 constexpr inline typename numbers::NumberTraits<Number>::real_type
2353 compute_norm(const typename SymmetricTensorAccessors::
2354 StorageType<2, dim, Number>::base_tensor_type &data)
2355 {
2356 // Make things work with AD types
2357 using std::sqrt;
2358 switch (dim)
2359 {
2360 case 1:
2361 return numbers::NumberTraits<Number>::abs(data[0]);
2362
2363 case 2:
2364 return sqrt(numbers::NumberTraits<Number>::abs_square(data[0]) +
2365 numbers::NumberTraits<Number>::abs_square(data[1]) +
2366 2. * numbers::NumberTraits<Number>::abs_square(data[2]));
2367
2368 case 3:
2369 return sqrt(numbers::NumberTraits<Number>::abs_square(data[0]) +
2370 numbers::NumberTraits<Number>::abs_square(data[1]) +
2371 numbers::NumberTraits<Number>::abs_square(data[2]) +
2372 2. * numbers::NumberTraits<Number>::abs_square(data[3]) +
2373 2. * numbers::NumberTraits<Number>::abs_square(data[4]) +
2374 2. * numbers::NumberTraits<Number>::abs_square(data[5]));
2375
2376 default:
2377 {
2378 typename numbers::NumberTraits<Number>::real_type return_value =
2379 typename numbers::NumberTraits<Number>::real_type();
2380
2381 for (unsigned int d = 0; d < dim; ++d)
2382 return_value +=
2383 numbers::NumberTraits<Number>::abs_square(data[d]);
2384 for (unsigned int d = dim; d < (dim * dim + dim) / 2; ++d)
2385 return_value +=
2386 2. * numbers::NumberTraits<Number>::abs_square(data[d]);
2387
2388 return sqrt(return_value);
2389 }
2390 }
2391 }
2392
2393
2394
2395 template <int dim, typename Number>
2396 constexpr inline typename numbers::NumberTraits<Number>::real_type
2397 compute_norm(const typename SymmetricTensorAccessors::
2398 StorageType<4, dim, Number>::base_tensor_type &data)
2399 {
2400 // Make things work with AD types
2401 using std::sqrt;
2402 switch (dim)
2403 {
2404 case 1:
2405 return numbers::NumberTraits<Number>::abs(data[0][0]);
2406
2407 default:
2408 {
2409 typename numbers::NumberTraits<Number>::real_type return_value =
2410 typename numbers::NumberTraits<Number>::real_type();
2411
2412 const unsigned int n_independent_components = data.dimension;
2413
2414 for (unsigned int i = 0; i < dim; ++i)
2415 for (unsigned int j = 0; j < dim; ++j)
2416 return_value +=
2417 numbers::NumberTraits<Number>::abs_square(data[i][j]);
2418 for (unsigned int i = 0; i < dim; ++i)
2419 for (unsigned int j = dim; j < n_independent_components; ++j)
2420 return_value +=
2421 2. * numbers::NumberTraits<Number>::abs_square(data[i][j]);
2422 for (unsigned int i = dim; i < n_independent_components; ++i)
2423 for (unsigned int j = 0; j < dim; ++j)
2424 return_value +=
2425 2. * numbers::NumberTraits<Number>::abs_square(data[i][j]);
2426 for (unsigned int i = dim; i < n_independent_components; ++i)
2427 for (unsigned int j = dim; j < n_independent_components; ++j)
2428 return_value +=
2429 4. * numbers::NumberTraits<Number>::abs_square(data[i][j]);
2430
2431 return sqrt(return_value);
2432 }
2433 }
2434 }
2435
2436 } // end of namespace internal
2437
2438
2439
2440 template <int rank_, int dim, typename Number>
2441 DEAL_II_HOST constexpr typename numbers::NumberTraits<Number>::real_type
2442 SymmetricTensor<rank_, dim, Number>::norm() const
2443 {
2444 return internal::compute_norm<dim, Number>(data);
2445 }
2446
2447
2448
2449 template <int rank_, int dim, typename Number>
2450 DEAL_II_HOST constexpr unsigned int
2451 SymmetricTensor<rank_, dim, Number>::component_to_unrolled_index(
2452 const TableIndices<rank_> &indices)
2453 {
2454 return internal::SymmetricTensorImplementation::component_to_unrolled_index<
2455 dim>(indices);
2456 }
2457
2458
2459
2460 namespace internal
2461 {
2462 namespace SymmetricTensorImplementation
2463 {
2464 // a function to do the inverse of the unrolling from a set of
2465 // indices to a scalar index into the array in which we store
2466 // the elements of a symmetric tensor. in other words, it goes
2467 // from the scalar index into the array to a set of indices of
2468 // the tensor
2469 //
2470 // this function is for rank-2 tensors
2471 template <int dim>
2472 constexpr inline DEAL_II_ALWAYS_INLINE TableIndices<2>
2473 unrolled_to_component_indices(const unsigned int i,
2474 const std::integral_constant<int, 2> &)
2475 {
2476 Assert(
2477 (i < dealii::SymmetricTensor<2, dim, double>::n_independent_components),
2478 ExcIndexRange(
2479 i,
2480 0,
2481 dealii::SymmetricTensor<2, dim, double>::n_independent_components));
2482 switch (dim)
2483 {
2484 case 1:
2485 {
2486 return {0, 0};
2487 }
2488
2489 case 2:
2490 {
2491 const TableIndices<2> table[3] = {TableIndices<2>(0, 0),
2492 TableIndices<2>(1, 1),
2493 TableIndices<2>(0, 1)};
2494 return table[i];
2495 }
2496
2497 case 3:
2498 {
2499 const TableIndices<2> table[6] = {TableIndices<2>(0, 0),
2500 TableIndices<2>(1, 1),
2501 TableIndices<2>(2, 2),
2502 TableIndices<2>(0, 1),
2503 TableIndices<2>(0, 2),
2504 TableIndices<2>(1, 2)};
2505 return table[i];
2506 }
2507
2508 default:
2509 if (i < dim)
2510 return {i, i};
2511
2512 for (unsigned int d = 0, c = dim; d < dim; ++d)
2513 for (unsigned int e = d + 1; e < dim; ++e, ++c)
2514 if (c == i)
2515 return {d, e};
2516
2517 // should never get here:
2518 DEAL_II_ASSERT_UNREACHABLE();
2519 return {0, 0};
2520 }
2521 }
2522
2523 // a function to do the inverse of the unrolling from a set of
2524 // indices to a scalar index into the array in which we store
2525 // the elements of a symmetric tensor. in other words, it goes
2526 // from the scalar index into the array to a set of indices of
2527 // the tensor
2528 //
2529 // this function is for tensors of a rank not already handled
2530 // above
2531 template <int dim, int rank_>
2532 constexpr inline std::enable_if_t<rank_ != 2, TableIndices<rank_>>
2533 unrolled_to_component_indices(const unsigned int i,
2534 const std::integral_constant<int, rank_> &)
2535 {
2536 (void)i;
2537 Assert(
2538 (i <
2539 dealii::SymmetricTensor<rank_, dim, double>::n_independent_components),
2540 ExcIndexRange(i,
2541 0,
2542 dealii::SymmetricTensor<rank_, dim, double>::
2543 n_independent_components));
2544 DEAL_II_NOT_IMPLEMENTED();
2545 return TableIndices<rank_>();
2546 }
2547
2548 } // namespace SymmetricTensorImplementation
2549 } // namespace internal
2550
2551 template <int rank_, int dim, typename Number>
2552 DEAL_II_HOST constexpr DEAL_II_ALWAYS_INLINE TableIndices<rank_>
2553 SymmetricTensor<rank_, dim, Number>::unrolled_to_component_indices(
2554 const unsigned int i)
2555 {
2556 return internal::SymmetricTensorImplementation::unrolled_to_component_indices<
2557 dim>(i, std::integral_constant<int, rank_>());
2558 }
2559
2560
2561
2562 template <int rank_, int dim, typename Number>
2563 template <class Archive>
2564 inline void
2565 SymmetricTensor<rank_, dim, Number>::serialize(Archive &ar, const unsigned int)
2566 {
2567 ar &data;
2568 }
2569
2570
2571 #endif // DOXYGEN
2572
2573 /* ----------------- Non-member functions operating on tensors. ------------ */
2574
2575
2576 /**
2577 * Addition of two symmetric tensors of equal rank. The result is another
2578 * SymmetricTensor that has a number type that is compatible with the
2579 * operation.
2580 *
2581 * If possible (e.g. when @p Number and @p OtherNumber are of the same type,
2582 * or if the result of <code>Number() + OtherNumber()</code> is another @p Number),
2583 * you should use <tt>operator+=</tt> instead since this does not require the
2584 * creation of a temporary variable.
2585 *
2586 * @relatesalso SymmetricTensor
2587 */
2588 template <int rank_, int dim, typename Number, typename OtherNumber>
2589 DEAL_II_HOST constexpr inline DEAL_II_ALWAYS_INLINE
2590 SymmetricTensor<rank_, dim, typename ProductType<Number, OtherNumber>::type>
2591 operator+(const SymmetricTensor<rank_, dim, Number> &left,
2592 const SymmetricTensor<rank_, dim, OtherNumber> &right)
2593 {
2594 SymmetricTensor<rank_, dim, typename ProductType<Number, OtherNumber>::type>
2595 tmp = left;
2596 tmp += right;
2597 return tmp;
2598 }
2599
2600
2601 /**
2602 * Subtraction of two symmetric tensors of equal rank. The result is another
2603 * SymmetricTensor that has a number type that is compatible with the
2604 * operation.
2605 *
2606 * If possible (e.g. when @p Number and @p OtherNumber are of the same type,
2607 * or if the result of <code>Number() - OtherNumber()</code> is another @p Number),
2608 * you should use <tt>operator-=</tt> instead since this does not require the
2609 * creation of a temporary variable.
2610 *
2611 * @relatesalso SymmetricTensor
2612 */
2613 template <int rank_, int dim, typename Number, typename OtherNumber>
2614 DEAL_II_HOST constexpr inline DEAL_II_ALWAYS_INLINE
2615 SymmetricTensor<rank_, dim, typename ProductType<Number, OtherNumber>::type>
2616 operator-(const SymmetricTensor<rank_, dim, Number> &left,
2617 const SymmetricTensor<rank_, dim, OtherNumber> &right)
2618 {
2619 SymmetricTensor<rank_, dim, typename ProductType<Number, OtherNumber>::type>
2620 tmp = left;
2621 tmp -= right;
2622 return tmp;
2623 }
2624
2625
2626 /**
2627 * Addition of a SymmetricTensor and a general Tensor of equal rank. The
2628 * result is a general Tensor that has a number type that is compatible with the
2629 * operation.
2630 *
2631 * @relatesalso SymmetricTensor
2632 */
2633 template <int rank_, int dim, typename Number, typename OtherNumber>
2634 DEAL_II_HOST constexpr DEAL_II_ALWAYS_INLINE
2635 Tensor<rank_, dim, typename ProductType<Number, OtherNumber>::type>
2636 operator+(const SymmetricTensor<rank_, dim, Number> &left,
2637 const Tensor<rank_, dim, OtherNumber> &right)
2638 {
2639 return Tensor<rank_, dim, Number>(left) + right;
2640 }
2641
2642
2643 /**
2644 * Addition of a general Tensor with a SymmetricTensor of equal rank. The
2645 * result is a general Tensor that has a number type that is compatible with the
2646 * operation.
2647 *
2648 * @relatesalso SymmetricTensor
2649 */
2650 template <int rank_, int dim, typename Number, typename OtherNumber>
2651 DEAL_II_HOST constexpr DEAL_II_ALWAYS_INLINE
2652 Tensor<rank_, dim, typename ProductType<Number, OtherNumber>::type>
2653 operator+(const Tensor<rank_, dim, Number> &left,
2654 const SymmetricTensor<rank_, dim, OtherNumber> &right)
2655 {
2656 return left + Tensor<rank_, dim, OtherNumber>(right);
2657 }
2658
2659
2660 /**
2661 * Subtraction of a general Tensor from a SymmetricTensor of equal rank. The
2662 * result is a general Tensor that has a number type that is compatible with the
2663 * operation.
2664 *
2665 * @relatesalso SymmetricTensor
2666 */
2667 template <int rank_, int dim, typename Number, typename OtherNumber>
2668 DEAL_II_HOST constexpr DEAL_II_ALWAYS_INLINE
2669 Tensor<rank_, dim, typename ProductType<Number, OtherNumber>::type>
2670 operator-(const SymmetricTensor<rank_, dim, Number> &left,
2671 const Tensor<rank_, dim, OtherNumber> &right)
2672 {
2673 return Tensor<rank_, dim, Number>(left) - right;
2674 }
2675
2676
2677 /**
2678 * Subtraction of a SymmetricTensor from a general Tensor of equal rank. The
2679 * result is a general Tensor that has a number type that is compatible with the
2680 * operation.
2681 *
2682 * @relatesalso SymmetricTensor
2683 */
2684 template <int rank_, int dim, typename Number, typename OtherNumber>
2685 DEAL_II_HOST constexpr DEAL_II_ALWAYS_INLINE
2686 Tensor<rank_, dim, typename ProductType<Number, OtherNumber>::type>
2687 operator-(const Tensor<rank_, dim, Number> &left,
2688 const SymmetricTensor<rank_, dim, OtherNumber> &right)
2689 {
2690 return left - Tensor<rank_, dim, OtherNumber>(right);
2691 }
2692
2693
2694
2695 template <int dim, typename Number>
2696 DEAL_II_HOST DEAL_II_CONSTEXPR inline DEAL_II_ALWAYS_INLINE Number
2697 determinant(const SymmetricTensor<2, dim, Number> &t)
2698 {
2699 switch (dim)
2700 {
2701 case 1:
2702 return t.data[0];
2703 case 2:
2704 return (t.data[0] * t.data[1] - t.data[2] * t.data[2]);
2705 case 3:
2706 {
2707 // in analogy to general tensors, but
2708 // there's something to be simplified for
2709 // the present case
2710 const Number tmp = t.data[3] * t.data[4] * t.data[5];
2711 return (tmp + tmp + t.data[0] * t.data[1] * t.data[2] -
2712 t.data[0] * t.data[5] * t.data[5] -
2713 t.data[1] * t.data[4] * t.data[4] -
2714 t.data[2] * t.data[3] * t.data[3]);
2715 }
2716 default:
2717 DEAL_II_NOT_IMPLEMENTED();
2718 return internal::NumberType<Number>::value(0.0);
2719 }
2720 }
2721
2722
2723
2724 /**
2725 * Compute the determinant of a rank 2 symmetric tensor. This function
2726 * therefore computes the same value as the <tt>determinant()</tt> functions
2727 * and is only provided for greater notational simplicity (since there are
2728 * also functions first_invariant() and second_invariant()).
2729 * \f[
2730 * I_3 (\mathbf A) = III (\mathbf A) = \det (\mathbf A)
2731 * \f]
2732 *
2733 * @relatesalso SymmetricTensor
2734 */
2735 template <int dim, typename Number>
2736 DEAL_II_HOST DEAL_II_CONSTEXPR DEAL_II_ALWAYS_INLINE Number
2737 third_invariant(const SymmetricTensor<2, dim, Number> &t)
2738 {
2739 return determinant(t);
2740 }
2741
2742
2743
2744 template <int dim, typename Number>
2745 DEAL_II_HOST constexpr inline DEAL_II_ALWAYS_INLINE Number
2746 trace(const SymmetricTensor<2, dim, Number> &d)
2747 {
2748 Number t = d.data[0];
2749 for (unsigned int i = 1; i < dim; ++i)
2750 t += d.data[i];
2751 return t;
2752 }
2753
2754
2755 /**
2756 * Compute the trace of a rank 2 symmetric tensor. This function therefore
2757 * computes the same value as the <tt>trace()</tt> functions and is only
2758 * provided for greater notational simplicity (since there are also functions
2759 * second_invariant() and third_invariant()).
2760 * \f[
2761 * I_1 (\mathbf A) = I (\mathbf A) = \text{tr} \mathbf A = \sum_i A_{ii}
2762 * \f]
2763 *
2764 * @relatesalso SymmetricTensor
2765 */
2766 template <int dim, typename Number>
2767 DEAL_II_HOST constexpr Number
2768 first_invariant(const SymmetricTensor<2, dim, Number> &t)
2769 {
2770 return trace(t);
2771 }
2772
2773
2774 /**
2775 * Compute the second invariant of a tensor of rank 2. The second invariant of
2776 * a tensor $\mathbf A$ is defined as
2777 * $I_2 (\mathbf A) = II(\mathbf A) = \frac 12
2778 * \left[ (\text{tr} \mathbf A)^2 - \text{tr} (\mathbf{A}^2) \right]$.
2779 *
2780 * For the kind of arguments to this function, i.e., a rank-2 tensor of
2781 * size 1, the result is simply zero.
2782 *
2783 * @relatesalso SymmetricTensor
2784 */
2785 template <typename Number>
2786 DEAL_II_HOST constexpr DEAL_II_ALWAYS_INLINE Number
2787 second_invariant(const SymmetricTensor<2, 1, Number> &)
2788 {
2789 return internal::NumberType<Number>::value(0.0);
2790 }
2791
2792
2793
2794 /**
2795 * Compute the second invariant of a tensor of rank 2. The second invariant of
2796 * a tensor $\mathbf A$ is defined as
2797 * $I_2 (\mathbf A) = II(\mathbf A) = \frac 12
2798 * \left[ (\text{tr} \mathbf A)^2 - \text{tr} (\mathbf{A}^2) \right]$.
2799 *
2800 * For the kind of arguments to this function, i.e., a symmetric rank-2 tensor
2801 * of size 2, the result is (counting indices starting at one)
2802 * $I_2(\mathbf A) = II(\mathbf A) = \frac 12
2803 * \left[ (A_{11} + A_{22})^2 - (A_{11}^2+2 A_{12}^2+ A_{22}^2) \right]
2804 * = A_{11} A_{22} - A_{12}^2$. As expected, for the
2805 * $2\times 2$ symmetric tensors this function handles, this equals the
2806 * determinant of the tensor. (This is so because for $2\times 2$ symmetric
2807 * tensors, there really are only two invariants, so the second and third
2808 * invariant are the same; the determinant is the third invariant.)
2809 *
2810 * @relatesalso SymmetricTensor
2811 */
2812 template <typename Number>
2813 DEAL_II_HOST constexpr DEAL_II_ALWAYS_INLINE Number
2814 second_invariant(const SymmetricTensor<2, 2, Number> &t)
2815 {
2816 return t[0][0] * t[1][1] - t[0][1] * t[0][1];
2817 }
2818
2819
2820
2821 /**
2822 * Compute the second invariant of a tensor of rank 2. The second invariant of
2823 * a tensor $\mathbf A$ is defined as
2824 * $I_2 (\mathbf A) = II(\mathbf A) = \frac 12
2825 * \left[ (\text{tr} \mathbf A)^2 - \text{tr} (\mathbf{A}^2) \right]$.
2826 *
2827 * @relatesalso SymmetricTensor
2828 */
2829 template <typename Number>
2830 DEAL_II_HOST constexpr DEAL_II_ALWAYS_INLINE Number
2831 second_invariant(const SymmetricTensor<2, 3, Number> &t)
2832 {
2833 return (t[0][0] * t[1][1] + t[1][1] * t[2][2] + t[2][2] * t[0][0] -
2834 t[0][1] * t[0][1] - t[0][2] * t[0][2] - t[1][2] * t[1][2]);
2835 }
2836
2837
2838
2839 /**
2840 * Return the eigenvalues of a symmetric $1 \times 1$ tensor.
2841 * The (single) entry of the tensor is, of course, equal to the (single)
2842 * eigenvalue.
2843 *
2844 * @relatesalso SymmetricTensor
2845 */
2846 template <typename Number>
2847 std::array<Number, 1>
2848 eigenvalues(const SymmetricTensor<2, 1, Number> &T);
2849
2850
2851
2852 /**
2853 * Return the eigenvalues of a symmetric $2\times 2$ tensor.
2854 * The array of eigenvalues is sorted in descending order.
2855 *
2856 * For $2\times 2$ tensors, the eigenvalues of tensor $\mathbf T$ are the
2857 * roots of <a
2858 * href="https://en.wikipedia.org/wiki/Eigenvalue_algorithm#2.C3.972_matrices">the
2859 * characteristic polynomial</a> $0 = \lambda^2
2860 * - \lambda\;\text{tr}\mathbf{T} + \det \mathbf{T}$ as given by
2861 * $\lambda_1, \lambda_2 = \frac{1}{2} \left[ \text{tr} \mathbf{T} \pm
2862 * \sqrt{(\text{tr} \mathbf{T})^2 - 4 \det \mathbf{T}} \right]$.
2863 *
2864 * @warning The algorithm employed here determines the eigenvalues by
2865 * computing the roots of the characteristic polynomial. In the case that there
2866 * exists a common root (the eigenvalues are equal), the computation is
2867 * <a href="https://scicomp.stackexchange.com/q/23686">subject to round-off
2868 * errors</a> of order $\sqrt{\epsilon}$. As an alternative, the eigenvectors()
2869 * function provides a more robust, but costly, method to compute the
2870 * eigenvalues of a symmetric tensor.
2871 *
2872 * @relatesalso SymmetricTensor
2873 */
2874 template <typename Number>
2875 std::array<Number, 2>
2876 eigenvalues(const SymmetricTensor<2, 2, Number> &T);
2877
2878
2879
2880 /**
2881 * Return the eigenvalues of a symmetric $3\times 3$ tensor.
2882 * The array of eigenvalues is sorted in descending order.
2883 *
2884 * For $3\times 3$ tensors, the eigenvalues of tensor $\mathbf T$ are the
2885 * roots of <a
2886 * href="https://en.wikipedia.org/wiki/Eigenvalue_algorithm#3.C3.973_matrices">the
2887 * characteristic polynomial</a> $0 = \lambda^3 - \lambda^2\;\text{tr}\mathbf T
2888 * - \frac{1}{2} \lambda
2889 * \left[\text{tr}(\mathbf{T}^2) - (\text{tr}\mathbf T)^2\right] -
2890 * \det \mathbf T$.
2891 *
2892 * @warning The algorithm employed here determines the eigenvalues by
2893 * computing the roots of the characteristic polynomial. In the case that there
2894 * exists a common root (the eigenvalues are equal), the computation is
2895 * <a href="https://scicomp.stackexchange.com/q/23686">subject to round-off
2896 * errors</a> of order $\sqrt{\epsilon}$. As an alternative, the eigenvectors()
2897 * function provides a more robust, but costly, method to compute the
2898 * eigenvalues of a symmetric tensor.
2899 *
2900 * @relatesalso SymmetricTensor
2901 */
2902 template <typename Number>
2903 std::array<Number, 3>
2904 eigenvalues(const SymmetricTensor<2, 3, Number> &T);
2905
2906
2907
2908 namespace internal
2909 {
2910 namespace SymmetricTensorImplementation
2911 {
2912 /**
2913 * Tridiagonalize a rank-2 symmetric tensor using the Householder method.
2914 * The specialized algorithm implemented here is given in @cite Kopp2008
2915 * and is based off of the generic algorithm presented in section 11.3.2 of
2916 * @cite Press2007.
2917 *
2918 * @param[in] A This tensor to be tridiagonalized
2919 * @param[out] Q The orthogonal matrix effecting the transformation
2920 * @param[out] d The diagonal elements of the tridiagonal matrix
2921 * @param[out] e The off-diagonal elements of the tridiagonal matrix
2922 */
2923 template <int dim, typename Number>
2924 void
2925 tridiagonalize(const dealii::SymmetricTensor<2, dim, Number> &A,
2926 dealii::Tensor<2, dim, Number> &Q,
2927 std::array<Number, dim> &d,
2928 std::array<Number, dim - 1> &e);
2929
2930
2931
2932 /**
2933 * Compute the eigenvalues and eigenvectors of a real-valued rank-2
2934 * symmetric tensor using the QL algorithm with implicit shifts.
2935 * The specialized algorithm implemented here is given in @cite Kopp2008
2936 * and is based off of the generic algorithm presented in section 11.4.3 of
2937 * @cite Press2007.
2938 *
2939 * @param[in] A The tensor of which the eigenvectors and eigenvalues are
2940 * to be computed.
2941 *
2942 * @return An array containing the eigenvectors and the associated eigenvalues.
2943 * The array is not sorted in any particular order.
2944 */
2945 template <int dim, typename Number>
2946 std::array<std::pair<Number, Tensor<1, dim, Number>>, dim>
2947 ql_implicit_shifts(const dealii::SymmetricTensor<2, dim, Number> &A);
2948
2949
2950
2951 /**
2952 * Compute the eigenvalues and eigenvectors of a real-valued rank-2
2953 * symmetric tensor using the Jacobi algorithm.
2954 * The specialized algorithm implemented here is given in @cite Kopp2008
2955 * and is based off of the generic algorithm presented in section 11.4.3 of
2956 * @cite Press2007.
2957 *
2958 * @param[in] A The tensor of which the eigenvectors and eigenvalues are
2959 * to be computed.
2960 *
2961 * @return An array containing the eigenvectors and the associated eigenvalues.
2962 * The array is not sorted in any particular order.
2963 */
2964 template <int dim, typename Number>
2965 std::array<std::pair<Number, Tensor<1, dim, Number>>, dim>
2966 jacobi(dealii::SymmetricTensor<2, dim, Number> A);
2967
2968
2969
2970 /**
2971 * Compute the eigenvalues and eigenvectors of a real-valued rank-2
2972 * symmetric 2x2 tensor using the characteristic equation to compute
2973 * eigenvalues and an analytical approach based on the cross-product for the
2974 * eigenvectors. If the computations are deemed too inaccurate then the
2975 * method falls back to ql_implicit_shifts.
2976 *
2977 * @param[in] A The tensor of which the eigenvectors and eigenvalues are
2978 * to be computed.
2979 *
2980 * @return An array containing the eigenvectors and the associated eigenvalues.
2981 * The array is not sorted in any particular order.
2982 */
2983 template <typename Number>
2984 std::array<std::pair<Number, Tensor<1, 2, Number>>, 2>
2985 hybrid(const dealii::SymmetricTensor<2, 2, Number> &A);
2986
2987
2988
2989 /**
2990 * Compute the eigenvalues and eigenvectors of a real-valued rank-2
2991 * symmetric 3x3 tensor using the characteristic equation to compute
2992 * eigenvalues and an analytical approach based on the cross-product for the
2993 * eigenvectors. If the computations are deemed too inaccurate then the
2994 * method falls back to ql_implicit_shifts. The specialized algorithm
2995 * implemented here is given in @cite Kopp2008.
2996 *
2997 * @param[in] A The tensor of which the eigenvectors and eigenvalues are
2998 * to be computed.
2999 *
3000 * @return An array containing the eigenvectors and the associated eigenvalues.
3001 * The array is not sorted in any particular order.
3002 */
3003 template <typename Number>
3004 std::array<std::pair<Number, Tensor<1, 3, Number>>, 3>
3005 hybrid(const dealii::SymmetricTensor<2, 3, Number> &A);
3006
3007 /**
3008 * A struct that is used to sort arrays of pairs of eign=envalues and
3009 * eigenvectors. Sorting is performed in descending order of eigenvalue.
3010 */
3011 template <int dim, typename Number>
3012 struct SortEigenValuesVectors
3013 {
3014 using EigValsVecs = std::pair<Number, Tensor<1, dim, Number>>;
3015 bool
3016 operator()(const EigValsVecs &lhs, const EigValsVecs &rhs)
3017 {
3018 return lhs.first > rhs.first;
3019 }
3020 };
3021
3022 } // namespace SymmetricTensorImplementation
3023
3024 } // namespace internal
3025
3026
3027
3028 // The line below is to ensure that doxygen puts the full description
3029 // of this global enumeration into the documentation
3030 // See https://stackoverflow.com/a/1717984
3031 /** @file */
3032 /**
3033 * An enumeration for the algorithm to be employed when performing
3034 * the computation of normalized eigenvectors and their corresponding
3035 * eigenvalues by the eigenvalues() and eigenvectors() methods operating on
3036 * SymmetricTensor objects.
3037 *
3038 * The specialized algorithms utilized in computing the eigenvectors are
3039 * presented in @cite Kopp2008.
3040 */
3041 enum struct SymmetricTensorEigenvectorMethod
3042 {
3043 /**
3044 * A hybrid approach that preferentially uses the characteristic equation to
3045 * compute eigenvalues and an analytical approach based on the cross-product
3046 * for the eigenvectors. If the computations are deemed too inaccurate then
3047 * the method falls back to ql_implicit_shifts.
3048 *
3049 * This method potentially offers the quickest computation if the pathological
3050 * case is not encountered.
3051 */
3052 hybrid,
3053 /**
3054 * The iterative QL algorithm with implicit shifts applied after
3055 * tridiagonalization of the tensor using the householder method.
3056 *
3057 * This method offers a compromise between speed of computation and its
3058 * robustness. This method is particularly useful when the elements
3059 * of $T$ have greatly varying magnitudes, which would typically lead to a
3060 * loss of accuracy when computing the smaller eigenvalues.
3061 */
3062 ql_implicit_shifts,
3063 /**
3064 * The iterative Jacobi algorithm.
3065 *
3066 * This method offers is the most robust of the available options, with
3067 * reliable results obtained for even the most pathological cases. It is,
3068 * however, the slowest algorithm of all of those implemented.
3069 */
3070 jacobi
3071 };
3072
3073
3074
3075 /**
3076 * Return the eigenvalues and eigenvectors of a real-valued rank-2 symmetric
3077 * tensor $\mathbf T$. The array of matched eigenvalue and eigenvector pairs
3078 * is sorted in descending order (determined by the eigenvalues).
3079 *
3080 * The specialized algorithms utilized in computing the eigenvectors are
3081 * presented in @cite Kopp2008.
3082 *
3083 * @relatesalso SymmetricTensor
3084 */
3085 template <int dim, typename Number>
3086 std::array<std::pair<Number, Tensor<1, dim, Number>>, dim>
3087 eigenvectors(const SymmetricTensor<2, dim, Number> &T,
3088 const SymmetricTensorEigenvectorMethod method =
3089 SymmetricTensorEigenvectorMethod::ql_implicit_shifts);
3090
3091
3092
3093 /**
3094 * Return the transpose of the given symmetric tensor. Since we are working
3095 * with symmetric objects, the transpose is of course the same as the original
3096 * tensor. This function mainly exists for compatibility with the Tensor
3097 * class.
3098 *
3099 * @relatesalso SymmetricTensor
3100 */
3101 template <int rank_, int dim, typename Number>
3102 DEAL_II_HOST constexpr DEAL_II_ALWAYS_INLINE SymmetricTensor<rank_, dim, Number>
3103 transpose(const SymmetricTensor<rank_, dim, Number> &t)
3104 {
3105 return t;
3106 }
3107
3108
3109
3110 template <int dim, typename Number>
3111 DEAL_II_HOST constexpr inline DEAL_II_ALWAYS_INLINE
3112 SymmetricTensor<2, dim, Number>
3113 deviator(const SymmetricTensor<2, dim, Number> &t)
3114 {
3115 SymmetricTensor<2, dim, Number> tmp = t;
3116
3117 // subtract scaled trace from the diagonal
3118 const Number tr = trace(t) * internal::NumberType<Number>::value(1.0 / dim);
3119 for (unsigned int i = 0; i < dim; ++i)
3120 tmp.data[i] -= tr;
3121
3122 return tmp;
3123 }
3124
3125
3126
3127 template <int dim, typename Number>
3128 DEAL_II_HOST DEAL_II_CONSTEXPR inline DEAL_II_ALWAYS_INLINE
3129 SymmetricTensor<2, dim, Number>
3130 unit_symmetric_tensor()
3131 {
3132 // create a default constructed matrix filled with
3133 // zeros, then set the diagonal elements to one
3134 SymmetricTensor<2, dim, Number> tmp;
3135 switch (dim)
3136 {
3137 case 1:
3138 tmp.data[0] = internal::NumberType<Number>::value(1.);
3139 break;
3140 case 2:
3141 tmp.data[0] = tmp.data[1] = internal::NumberType<Number>::value(1.);
3142 break;
3143 case 3:
3144 tmp.data[0] = tmp.data[1] = tmp.data[2] =
3145 internal::NumberType<Number>::value(1.);
3146 break;
3147 default:
3148 for (unsigned int d = 0; d < dim; ++d)
3149 tmp.data[d] = internal::NumberType<Number>::value(1.);
3150 }
3151 return tmp;
3152 }
3153
3154
3155
3156 template <int dim, typename Number>
3157 DEAL_II_HOST DEAL_II_CONSTEXPR inline SymmetricTensor<4, dim, Number>
3158 deviator_tensor()
3159 {
3160 SymmetricTensor<4, dim, Number> tmp;
3161
3162 // fill the elements treating the diagonal
3163 for (unsigned int i = 0; i < dim; ++i)
3164 for (unsigned int j = 0; j < dim; ++j)
3165 tmp.data[i][j] =
3166 internal::NumberType<Number>::value((i == j ? 1. : 0.) - 1. / dim);
3167
3168 // then fill the ones that copy over the
3169 // non-diagonal elements. note that during
3170 // the double-contraction, we handle the
3171 // off-diagonal elements twice, so simply
3172 // copying requires a weight of 1/2
3173 for (unsigned int i = dim;
3174 i < internal::SymmetricTensorAccessors::StorageType<4, dim, Number>::
3175 n_rank2_components;
3176 ++i)
3177 tmp.data[i][i] = internal::NumberType<Number>::value(0.5);
3178
3179 return tmp;
3180 }
3181
3182
3183
3184 template <int dim, typename Number>
3185 DEAL_II_HOST DEAL_II_CONSTEXPR inline DEAL_II_ALWAYS_INLINE
3186 SymmetricTensor<4, dim, Number>
3187 identity_tensor()
3188 {
3189 SymmetricTensor<4, dim, Number> tmp;
3190
3191 // fill the elements treating the diagonal
3192 for (unsigned int i = 0; i < dim; ++i)
3193 tmp.data[i][i] = internal::NumberType<Number>::value(1.);
3194
3195 // then fill the ones that copy over the
3196 // non-diagonal elements. note that during
3197 // the double-contraction, we handle the
3198 // off-diagonal elements twice, so simply
3199 // copying requires a weight of 1/2
3200 for (unsigned int i = dim;
3201 i < internal::SymmetricTensorAccessors::StorageType<4, dim, Number>::
3202 n_rank2_components;
3203 ++i)
3204 tmp.data[i][i] = internal::NumberType<Number>::value(0.5);
3205
3206 return tmp;
3207 }
3208
3209
3210
3211 /**
3212 * Invert a symmetric rank-2 tensor.
3213 *
3214 * @note If a tensor is not invertible, then the result is unspecified, but will
3215 * likely contain the results of a division by zero or a very small number at
3216 * the very least.
3217 *
3218 * @relatesalso SymmetricTensor
3219 */
3220 template <int dim, typename Number>
3221 DEAL_II_HOST constexpr DEAL_II_ALWAYS_INLINE SymmetricTensor<2, dim, Number>
3222 invert(const SymmetricTensor<2, dim, Number> &t)
3223 {
3224 return internal::SymmetricTensorImplementation::Inverse<2, dim, Number>::
3225 value(t);
3226 }
3227
3228
3229
3230 /**
3231 * Invert a symmetric rank-4 tensor. Since symmetric rank-4 tensors are
3232 * mappings from and to symmetric rank-2 tensors, they can have an inverse.
3233 *
3234 * If a tensor is not invertible, then the result is unspecified, but will
3235 * likely contain the results of a division by zero or a very small number at
3236 * the very least.
3237 *
3238 * @relatesalso SymmetricTensor
3239 */
3240 template <int dim, typename Number>
3241 DEAL_II_HOST constexpr SymmetricTensor<4, dim, Number>
3242 invert(const SymmetricTensor<4, dim, Number> &t)
3243 {
3244 return internal::SymmetricTensorImplementation::Inverse<4, dim, Number>::
3245 value(t);
3246 }
3247
3248
3249
3250 /**
3251 * Return the tensor of rank 4 that is the outer product of the two tensors
3252 * given as arguments, i.e. the result
3253 * $\mathbb A = \mathbf{T}_1 \otimes \mathbf{T}_2$ satisfies
3254 * $\mathbb A : \mathbf B = (\mathbf{T}_2 : \mathbf B) \mathbf{T}_1$
3255 * for all symmetric tensors $\mathbf B$. In index notation
3256 * \f[
3257 * \mathcal{A}_{ijkl} = (T_1)_{ij} (T_2)_{kl}
3258 * \f]
3259 *
3260 * For example, the deviator tensor
3261 * $\mathbb P = \mathbb I - \frac{1}{\text{dim}} \mathbf I \otimes \mathbf I$
3262 * can be computed as
3263 * <tt>identity_tensor<dim>() - 1/d *
3264 * outer_product (unit_symmetric_tensor<dim>(),
3265 * unit_symmetric_tensor<dim>())</tt>,
3266 * since the (double) contraction with the unit tensor yields the trace
3267 * of a symmetric tensor ($\mathbf I : \mathbf B = \text{tr} \mathbf B$).
3268 *
3269 * @relatesalso SymmetricTensor
3270 */
3271 template <int dim, typename Number>
3272 DEAL_II_HOST constexpr inline SymmetricTensor<4, dim, Number>
3273 outer_product(const SymmetricTensor<2, dim, Number> &t1,
3274 const SymmetricTensor<2, dim, Number> &t2)
3275 {
3276 SymmetricTensor<4, dim, Number> tmp;
3277
3278 // fill only the elements really needed
3279 for (unsigned int i = 0; i < dim; ++i)
3280 for (unsigned int j = i; j < dim; ++j)
3281 for (unsigned int k = 0; k < dim; ++k)
3282 for (unsigned int l = k; l < dim; ++l)
3283 tmp[i][j][k][l] = t1[i][j] * t2[k][l];
3284
3285 return tmp;
3286 }
3287
3288 /**
3289 * Perform a spectrum decomposition of a 2nd-order symmetric tensor @a
3290 * original_tensor given as the input argument, \f[ \mathrm{original\_tensor} =
3291 * \sum_i \lambda_i \, \boldsymbol{n}_i \otimes \boldsymbol{n}_i, \f] where
3292 * $\lambda_i$ is the eigenvalue, and $\boldsymbol{n}_i$ is the corresponding
3293 * eigenvector. The output is a pair of 2nd-order symmetric tensors.
3294 * The first term in the pair is the positive
3295 * part of the input tensor, and the second term in the pair is the negative
3296 * part of the input tensor, that is,
3297 * \f[
3298 * \mathrm{positive\_part\_tensor} = \sum_i \left<\lambda_i\right>_+
3299 * \boldsymbol{n}_i \otimes \boldsymbol{n}_i, \quad
3300 * \mathrm{negative\_part\_tensor} = \sum_i \left<\lambda_i\right>_-
3301 * \boldsymbol{n}_i \otimes \boldsymbol{n}_i, \f] where
3302 * $\left<\lambda_i\right>_+ = \mathrm{max}\{ \lambda_i, 0 \}$ and
3303 * $\left<\lambda_i\right>_- = \mathrm{min}\{ \lambda_i, 0 \}$. Obviously,
3304 * \f[
3305 * \mathrm{positive\_part\_tensor} + \mathrm{negative\_part\_tensor} =
3306 * \mathrm{original\_tensor}. \f]
3307 *
3308 * @param[in] original_tensor The 2nd-order symmetric tensor to be split into
3309 * the positive and negative parts
3310 *
3311 * @relatesalso SymmetricTensor
3312 */
3313 template <int dim, typename Number>
3314 std::pair<SymmetricTensor<2, dim, Number>, SymmetricTensor<2, dim, Number>>
3315 positive_negative_split(const SymmetricTensor<2, dim, Number> &original_tensor)
3316 {
3317 Assert(dim <= 3, ExcNotImplemented());
3318
3319 const std::array<std::pair<Number, Tensor<1, dim, Number>>, dim>
3320 eigen_system = eigenvectors(original_tensor);
3321
3322 std::pair<SymmetricTensor<2, dim, Number>, SymmetricTensor<2, dim, Number>>
3323 positive_negative_tensors;
3324
3325 auto &[positive_part_tensor, negative_part_tensor] =
3326 positive_negative_tensors;
3327
3328 positive_part_tensor = 0;
3329 for (unsigned int i = 0; i < dim; ++i)
3330 if (eigen_system[i].first > 0)
3331 positive_part_tensor += eigen_system[i].first *
3332 symmetrize(outer_product(eigen_system[i].second,
3333 eigen_system[i].second));
3334
3335 negative_part_tensor = 0;
3336 for (unsigned int i = 0; i < dim; ++i)
3337 if (eigen_system[i].first < 0)
3338 negative_part_tensor += eigen_system[i].first *
3339 symmetrize(outer_product(eigen_system[i].second,
3340 eigen_system[i].second));
3341
3342 return positive_negative_tensors;
3343 }
3344
3345 /**
3346 * This function is similar to the function positive_negative_split(). That is,
3347 * perform a spectrum decomposition of a 2nd-order symmetric tensor @a
3348 * original_tensor given as the input argument, and split it into a positive
3349 * part and a negative part. Moreover, this function also provides the
3350 * derivatives. Let $\mathbf{A}$ represent the input 2nd-order symmetric tensor
3351 * @a original_tensor,
3352 * $\mathbf{A}^+$ represent the positive part, and
3353 * $\mathbf{A}^-$ represent the negative part. Then, two
3354 * fourth-order tensors are defined as
3355 * \f[
3356 * \mathbb{P}^+ = \frac{\partial \mathbf{A}^+}{\partial \mathbf{A}}, \quad
3357 * \mathbb{P}^- = \frac{\partial \mathbf{A}^-}{\partial \mathbf{A}},
3358 * \f]
3359 * where $\mathbb{P}^+$ is the positive projector and $\mathbb{P}^-$ is the
3360 * negative projector. These two fourth-order tensors satisfy the following
3361 * properties: \f[ \mathbb{P}^+ : \mathbf{A} = \mathbf{A}^+, \quad \mathbb{P}^-
3362 * : \mathbf{A} = \mathbf{A}^-. \f] Since $\mathbb{P}^+$ and $\mathbb{P}^-$ are
3363 * 4th-order projectors, \f[ \mathbb{P}^+ : \mathbf{A}^+ = \mathbf{A}^+, \quad
3364 * \mathbb{P}^- : \mathbf{A}^- = \mathbf{A}^-, \quad \mathbb{P}^+ : \mathbf{A}^-
3365 * = \mathbb{P}^- : \mathbf{A}^+ = \mathbf{0}. \f] Lastly, \f[ \mathbb{P}^+ +
3366 * \mathbb{P}^- = \mathbb{S}, \f] where $\mathbb{S}$ is the fourth-order
3367 * symmetric identity tensor Physics::Elasticity::StandardTensors< dim >::S.
3368 * The output of this function is a tuple containing four terms.
3369 * The first term is $\mathbf{A}^+$, the second term is $\mathbf{A}^-$,
3370 * the third term is $\mathbb{P}^+$, and the fourth term is $\mathbb{P}^-$.
3371 *
3372 * @param[in] original_tensor The 2nd-order symmetric tensor to be split into
3373 * the positive and negative parts
3374 *
3375 * @relatesalso SymmetricTensor
3376 */
3377 template <int dim, typename Number>
3378 std::tuple<SymmetricTensor<2, dim, Number>,
3379 SymmetricTensor<2, dim, Number>,
3380 SymmetricTensor<4, dim, Number>,
3381 SymmetricTensor<4, dim, Number>>
3382 positive_negative_projectors(
3383 const SymmetricTensor<2, dim, Number> &original_tensor)
3384 {
3385 Assert(dim <= 3, ExcNotImplemented());
3386
3387 auto heaviside_function{[](const double x) {
3388 if (std::fabs(x) < 1.0e-16)
3389 return 0.5;
3390 if (x > 0)
3391 return 1.0;
3392 else
3393 return 0.0;
3394 }};
3395
3396 std::tuple<SymmetricTensor<2, dim, Number>,
3397 SymmetricTensor<2, dim, Number>,
3398 SymmetricTensor<4, dim, Number>,
3399 SymmetricTensor<4, dim, Number>>
3400 positive_negative_tensors_projectors;
3401
3402 auto &[positive_part_tensor,
3403 negative_part_tensor,
3404 positive_projector,
3405 negative_projector] = positive_negative_tensors_projectors;
3406
3407 const std::array<std::pair<Number, Tensor<1, dim, Number>>, dim>
3408 eigen_system = eigenvectors(original_tensor);
3409
3410 positive_part_tensor = 0;
3411 for (unsigned int i = 0; i < dim; ++i)
3412 if (eigen_system[i].first > 0)
3413 positive_part_tensor += eigen_system[i].first *
3414 symmetrize(outer_product(eigen_system[i].second,
3415 eigen_system[i].second));
3416
3417 negative_part_tensor = 0;
3418 for (unsigned int i = 0; i < dim; ++i)
3419 if (eigen_system[i].first < 0)
3420 negative_part_tensor += eigen_system[i].first *
3421 symmetrize(outer_product(eigen_system[i].second,
3422 eigen_system[i].second));
3423
3424 std::array<SymmetricTensor<2, dim, Number>, dim> M;
3425 for (unsigned int a = 0; a < dim; ++a)
3426 M[a] =
3427 symmetrize(outer_product(eigen_system[a].second, eigen_system[a].second));
3428
3429 std::array<SymmetricTensor<4, dim, Number>, dim> Q;
3430 for (unsigned int a = 0; a < dim; ++a)
3431 Q[a] = outer_product(M[a], M[a]);
3432
3433 std::array<std::array<SymmetricTensor<4, dim, Number>, dim>, dim> G;
3434 for (unsigned int a = 0; a < dim; ++a)
3435 for (unsigned int b = 0; b < dim; ++b)
3436 for (unsigned int i = 0; i < dim; ++i)
3437 for (unsigned int j = 0; j < dim; ++j)
3438 for (unsigned int k = 0; k < dim; ++k)
3439 for (unsigned int l = 0; l < dim; ++l)
3440 G[a][b][i][j][k][l] =
3441 M[a][i][k] * M[b][j][l] + M[a][i][l] * M[b][j][k];
3442
3443 // positive P
3444 positive_projector = 0;
3445 for (unsigned int a = 0; a < dim; ++a)
3446 {
3447 double lambda_a = eigen_system[a].first;
3448 positive_projector += heaviside_function(lambda_a) * Q[a];
3449 for (unsigned int b = 0; b < dim; ++b)
3450 {
3451 if (b != a)
3452 {
3453 double lambda_b = eigen_system[b].first;
3454
3455 double v_ab = 0.0;
3456 if (std::fabs(lambda_a - lambda_b) > 1.0e-12)
3457 v_ab = (std::fmax(lambda_a, 0.0) - std::fmax(lambda_b, 0.0)) /
3458 (lambda_a - lambda_b);
3459 else
3460 v_ab = 0.5 * (heaviside_function(lambda_a) +
3461 heaviside_function(lambda_b));
3462
3463 positive_projector += 0.5 * v_ab * 0.5 * (G[a][b] + G[b][a]);
3464 }
3465 }
3466 }
3467
3468 // negative P
3469 negative_projector = 0;
3470 for (unsigned int a = 0; a < dim; ++a)
3471 {
3472 double lambda_a = eigen_system[a].first;
3473 negative_projector += heaviside_function(-lambda_a) * Q[a];
3474 for (unsigned int b = 0; b < dim; ++b)
3475 {
3476 if (b != a)
3477 {
3478 double lambda_b = eigen_system[b].first;
3479
3480 double v_ab = 0.0;
3481 if (std::fabs(lambda_a - lambda_b) > 1.0e-12)
3482 v_ab = (std::fmin(lambda_a, 0.0) - std::fmin(lambda_b, 0.0)) /
3483 (lambda_a - lambda_b);
3484 else
3485 v_ab = 0.5 * (heaviside_function(-lambda_a) +
3486 heaviside_function(-lambda_b));
3487
3488 negative_projector += 0.5 * v_ab * 0.5 * (G[a][b] + G[b][a]);
3489 }
3490 }
3491 }
3492
3493 return positive_negative_tensors_projectors;
3494 }
3495
3496 /**
3497 * Return the symmetrized version of a full rank-2 tensor, i.e.
3498 * $\text{sym}\mathbf A = \frac 12 \left(\mathbf A + \mathbf{A}^T\right)$,
3499 * as a symmetric rank-2 tensor. This is the version for general dimensions.
3500 *
3501 * @relatesalso SymmetricTensor
3502 */
3503 template <int dim, typename Number>
3504 DEAL_II_HOST constexpr inline DEAL_II_ALWAYS_INLINE
3505 SymmetricTensor<2, dim, Number>
3506 symmetrize(const Tensor<2, dim, Number> &t)
3507 {
3508 SymmetricTensor<2, dim, Number> result;
3509 for (unsigned int d = 0; d < dim; ++d)
3510 result[d][d] = t[d][d];
3511
3512 const Number half = internal::NumberType<Number>::value(0.5);
3513 for (unsigned int d = 0; d < dim; ++d)
3514 for (unsigned int e = d + 1; e < dim; ++e)
3515 result[d][e] = (t[d][e] + t[e][d]) * half;
3516 return result;
3517 }
3518
3519
3520
3521 /**
3522 * Return the symmetrized version of a full rank-4 tensor, i.e.
3523 * as a symmetric rank-4 tensor. The symmetry could be of the following types:
3524 * Only minor: $A_{ijkl}=A_{jikl}=A_{ijlk}=A_{jilk}$.
3525 * Both minor and major: $A_{ijkl}=A_{jikl}=A_{ijlk}=A_{jilk}$ and
3526 * $A_{ijkl}=A_{klij}$. This is the version for general dimensions.
3527 * @param t The tensor to be symmetrized.
3528 * @param major_symmetry This argument decides the presence of major symmetry.
3529 *
3530 * @relatesalso SymmetricTensor
3531 */
3532 template <int dim, typename Number>
3533 DEAL_II_HOST constexpr inline DEAL_II_ALWAYS_INLINE
3534 SymmetricTensor<4, dim, Number>
3535 symmetrize(const Tensor<4, dim, Number> &t, const bool major_symmetry)
3536 {
3537 SymmetricTensor<4, dim, Number> result;
3538
3539 const Number half = internal::NumberType<Number>::value(0.5);
3540
3541 // minor symmetry - A_{ijkl}=A_{jikl}=A_{ijlk}=A_{jilk}
3542 for (unsigned int i = 0; i < dim; ++i)
3543 for (unsigned int j = 0; j < dim; ++j)
3544 for (unsigned int k = 0; k < dim; ++k)
3545 for (unsigned int l = 0; l < dim; ++l)
3546 {
3547 if (i != j && k == l)
3548 {
3549 // A_{ijkk}=A_{jikk}
3550 result[i][j][k][k] = (t[i][j][k][k] + t[j][i][k][k]) * half;
3551 }
3552 else if (i == j && k != l)
3553 {
3554 // A_{iikl}=A_{iilk}
3555 result[i][i][k][l] = (t[i][i][k][l] + t[i][i][l][k]) * half;
3556 }
3557 else if (i != j && k != l)
3558 {
3559 // A_{ijkl}=A_{jilk}
3560 result[i][j][k][l] = (t[i][j][k][l] + t[j][i][k][l] +
3561 t[i][j][l][k] + t[j][i][l][k]) *
3562 half * half;
3563 }
3564 else
3565 {
3566 // A_{iijj} and A_{iiii} unchanged
3567 result[i][j][k][l] = t[i][j][k][l];
3568 }
3569 }
3570
3571 // in case major symmetry is also required
3572 if (major_symmetry)
3573 {
3574 // major symmetry - A_{ijkl}=A_{klij}
3575 for (unsigned int i = 0; i < dim; ++i)
3576 for (unsigned int j = i; j < dim; ++j)
3577 for (unsigned int k = 0; k < dim; ++k)
3578 for (unsigned int l = k; l < dim; ++l)
3579 result[i][j][k][l] = (t[i][j][k][l] + t[k][l][i][j]) * half;
3580 }
3581 return result;
3582 }
3583
3584
3585
3586 /**
3587 * Multiplication of a symmetric tensor of general rank with a scalar from the
3588 * right. This version of the operator is used if the scalar has the same data
3589 * type as is used to store the elements of the symmetric tensor.
3590 *
3591 * @relatesalso SymmetricTensor
3592 */
3593 template <int rank_, int dim, typename Number>
3594 DEAL_II_HOST constexpr inline DEAL_II_ALWAYS_INLINE
3595 SymmetricTensor<rank_, dim, Number>
3596 operator*(const SymmetricTensor<rank_, dim, Number> &t, const Number &factor)
3597 {
3598 SymmetricTensor<rank_, dim, Number> tt = t;
3599 tt *= factor;
3600 return tt;
3601 }
3602
3603
3604
3605 /**
3606 * Multiplication of a symmetric tensor of general rank with a scalar from the
3607 * left. This version of the operator is used if the scalar has the same data
3608 * type as is used to store the elements of the symmetric tensor.
3609 *
3610 * @relatesalso SymmetricTensor
3611 */
3612 template <int rank_, int dim, typename Number>
3613 DEAL_II_HOST constexpr DEAL_II_ALWAYS_INLINE SymmetricTensor<rank_, dim, Number>
3614 operator*(const Number &factor, const SymmetricTensor<rank_, dim, Number> &t)
3615 {
3616 // simply forward to the other operator
3617 return t * factor;
3618 }
3619
3620
3621
3622 /**
3623 * Multiplication of a symmetric tensor with a scalar number from the right.
3624 *
3625 * The purpose of this operator is to enable only multiplication of a tensor
3626 * by a scalar number (i.e., a floating point number, a complex floating point
3627 * number, etc.). The function is written in a way that only allows the
3628 * compiler to consider the function if the second argument is indeed a scalar
3629 * number -- in other words, @p OtherNumber will not match, for example
3630 * <code>std::vector@<double@></code> as the product of a tensor and a vector
3631 * clearly would make no sense. The mechanism by which the compiler is
3632 * prohibited of considering this operator for multiplication with non-scalar
3633 * types are explained in the documentation of the EnableIfScalar class.
3634 *
3635 * The return type of the function is chosen so that it matches the types of
3636 * both the tensor and the scalar argument. For example, if you multiply a
3637 * <code>SymmetricTensor@<2,dim,double@></code> by
3638 * <code>std::complex@<double@></code>, then the result will be a
3639 * <code>SymmetricTensor@<2,dim,std::complex@<double@>@></code>. In other
3640 * words, the type with which the returned tensor stores its components equals
3641 * the type you would get if you multiplied an individual component of the
3642 * input tensor by the scalar factor.
3643 *
3644 * @relates SymmetricTensor
3645 */
3646 template <int rank_, int dim, typename Number, typename OtherNumber>
3647 DEAL_II_HOST constexpr inline DEAL_II_ALWAYS_INLINE SymmetricTensor<
3648 rank_,
3649 dim,
3650 typename ProductType<Number,
3651 typename EnableIfScalar<OtherNumber>::type>::type>
3652 operator*(const SymmetricTensor<rank_, dim, Number> &t,
3653 const OtherNumber &factor)
3654 {
3655 // form the product. we have to convert the two factors into the final
3656 // type via explicit casts because, for awkward reasons, the C++
3657 // standard committee saw it fit to not define an
3658 // operator*(float,std::complex<double>)
3659 // (as well as with switched arguments and double<->float).
3660 using product_type = typename ProductType<Number, OtherNumber>::type;
3661 SymmetricTensor<rank_, dim, product_type> tt(t);
3662 tt *= internal::NumberType<product_type>::value(factor);
3663 return tt;
3664 }
3665
3666
3667
3668 /**
3669 * Multiplication of a symmetric tensor with a scalar number from the left.
3670 * See the discussion with the operator with switched arguments for more
3671 * information about template arguments and the return type.
3672 *
3673 * @relates SymmetricTensor
3674 */
3675 template <int rank_, int dim, typename Number, typename OtherNumber>
3676 DEAL_II_HOST constexpr inline DEAL_II_ALWAYS_INLINE SymmetricTensor<
3677 rank_,
3678 dim,
3679 typename ProductType<OtherNumber,
3680 typename EnableIfScalar<Number>::type>::type>
3681 operator*(const Number &factor,
3682 const SymmetricTensor<rank_, dim, OtherNumber> &t)
3683 {
3684 // simply forward to the other operator with switched arguments
3685 return (t * factor);
3686 }
3687
3688
3689
3690 /**
3691 * Division of a symmetric tensor of general rank by a scalar.
3692 *
3693 * @relates SymmetricTensor
3694 */
3695 template <int rank_, int dim, typename Number, typename OtherNumber>
3696 DEAL_II_HOST constexpr inline SymmetricTensor<
3697 rank_,
3698 dim,
3699 typename ProductType<Number,
3700 typename EnableIfScalar<OtherNumber>::type>::type>
3701 operator/(const SymmetricTensor<rank_, dim, Number> &t,
3702 const OtherNumber &factor)
3703 {
3704 using product_type = typename ProductType<Number, OtherNumber>::type;
3705 SymmetricTensor<rank_, dim, product_type> tt(t);
3706 tt /= internal::NumberType<product_type>::value(factor);
3707 return tt;
3708 }
3709
3710
3711
3712 /**
3713 * Multiplication of a symmetric tensor of general rank with a scalar from the
3714 * right.
3715 *
3716 * @relates SymmetricTensor
3717 */
3718 template <int rank_, int dim>
3719 DEAL_II_HOST constexpr inline DEAL_II_ALWAYS_INLINE SymmetricTensor<rank_, dim>
3720 operator*(const SymmetricTensor<rank_, dim> &t, const double factor)
3721 {
3722 SymmetricTensor<rank_, dim> tt(t);
3723 tt *= factor;
3724 return tt;
3725 }
3726
3727
3728
3729 /**
3730 * Multiplication of a symmetric tensor of general rank with a scalar from the
3731 * left.
3732 *
3733 * @relates SymmetricTensor
3734 */
3735 template <int rank_, int dim>
3736 DEAL_II_HOST constexpr inline DEAL_II_ALWAYS_INLINE SymmetricTensor<rank_, dim>
3737 operator*(const double factor, const SymmetricTensor<rank_, dim> &t)
3738 {
3739 SymmetricTensor<rank_, dim> tt(t);
3740 tt *= factor;
3741 return tt;
3742 }
3743
3744
3745
3746 /**
3747 * Division of a symmetric tensor of general rank by a scalar.
3748 *
3749 * @relates SymmetricTensor
3750 */
3751 template <int rank_, int dim>
3752 DEAL_II_HOST constexpr inline SymmetricTensor<rank_, dim>
3753 operator/(const SymmetricTensor<rank_, dim> &t, const double factor)
3754 {
3755 SymmetricTensor<rank_, dim> tt(t);
3756 tt /= factor;
3757 return tt;
3758 }
3759
3760 /**
3761 * Compute the scalar product $\mathbf A: \mathbf B=\sum_{i,j} A_{ij}B_{ij}$
3762 * between two tensors $\mathbf A, \mathbf B$ of rank 2. In the current case
3763 * where both arguments are symmetric tensors, this is equivalent to calling
3764 * the expression <code>A*B</code> which uses
3765 * <code>SymmetricTensor::operator*()</code>.
3766 *
3767 * @relates SymmetricTensor
3768 */
3769 template <int dim, typename Number, typename OtherNumber>
3770 DEAL_II_HOST constexpr DEAL_II_ALWAYS_INLINE
3771 typename ProductType<Number, OtherNumber>::type
3772 scalar_product(const SymmetricTensor<2, dim, Number> &t1,
3773 const SymmetricTensor<2, dim, OtherNumber> &t2)
3774 {
3775 return (t1 * t2);
3776 }
3777
3778
3779 /**
3780 * Compute the scalar product $\mathbf A: \mathbf B=\sum_{i,j} A_{ij}B_{ij}$
3781 * between two tensors $\mathbf A, \mathbf B$ of rank 2. We don't use
3782 * <code>operator*</code> for this
3783 * operation since the product between two tensors is usually assumed to be
3784 * the contraction over the last index of the first tensor and the first index
3785 * of the second tensor. For example, if <tt>B</tt> is a Tensor, calling
3786 * <tt>A*B</tt> (instead of <tt>scalar_product(A,B)</tt>) provides
3787 * $(\mathbf A \cdot\mathbf B)_{ij}=\sum_k A_{ik}B_{kj}$.
3788 *
3789 * @relates SymmetricTensor
3790 */
3791 template <int dim, typename Number, typename OtherNumber>
3792 DEAL_II_HOST constexpr inline DEAL_II_ALWAYS_INLINE
3793 typename ProductType<Number, OtherNumber>::type
3794 scalar_product(const SymmetricTensor<2, dim, Number> &t1,
3795 const Tensor<2, dim, OtherNumber> &t2)
3796 {
3797 typename ProductType<Number, OtherNumber>::type s = internal::NumberType<
3798 typename ProductType<Number, OtherNumber>::type>::value(0.0);
3799 for (unsigned int i = 0; i < dim; ++i)
3800 for (unsigned int j = 0; j < dim; ++j)
3801 s += t1[i][j] * t2[i][j];
3802 return s;
3803 }
3804
3805
3806 /**
3807 * Compute the scalar product $\mathbf A:\mathbf B=\sum_{i,j} A_{ij}B_{ij}$
3808 * between two tensors $\mathbf A, \mathbf B$ of rank 2.
3809 * We don't use <code>operator*</code> for this
3810 * operation since the product between two tensors is usually assumed to be
3811 * the contraction over the last index of the first tensor and the first index
3812 * of the second tensor. For example, if <tt>A</tt> is a Tensor, calling
3813 * <tt>A*B</tt> (instead of <tt>scalar_product(A,B)</tt>) provides
3814 * $(\mathbf A \cdot\mathbf B)_{ij}=\sum_k A_{ik}B_{kj}$.
3815 *
3816 * @relates SymmetricTensor
3817 */
3818 template <int dim, typename Number, typename OtherNumber>
3819 DEAL_II_HOST constexpr DEAL_II_ALWAYS_INLINE
3820 typename ProductType<Number, OtherNumber>::type
3821 scalar_product(const Tensor<2, dim, Number> &t1,
3822 const SymmetricTensor<2, dim, OtherNumber> &t2)
3823 {
3824 return scalar_product(t2, t1);
3825 }
3826
3827
3828 /**
3829 * Double contraction between a rank-4 and a rank-2 symmetric tensor,
3830 * resulting in the symmetric tensor of rank 2 that is given as first argument
3831 * to this function. This operation is the symmetric tensor analogon of a
3832 * matrix-vector multiplication.
3833 *
3834 * This function does the same as SymmetricTensor::operator*().
3835 * It should not be used, however, since the member operator has
3836 * knowledge of the actual data storage format and is at least 2 orders of
3837 * magnitude faster. This function mostly exists for compatibility purposes
3838 * with the general Tensor class.
3839 *
3840 * @relates SymmetricTensor
3841 */
3842 template <typename Number, typename OtherNumber>
3843 DEAL_II_HOST constexpr inline DEAL_II_ALWAYS_INLINE void
3844 double_contract(
3845 SymmetricTensor<2, 1, typename ProductType<Number, OtherNumber>::type> &tmp,
3846 const SymmetricTensor<4, 1, Number> &t,
3847 const SymmetricTensor<2, 1, OtherNumber> &s)
3848 {
3849 tmp[0][0] = t[0][0][0][0] * s[0][0];
3850 }
3851
3852
3853
3854 /**
3855 * Double contraction between a rank-4 and a rank-2 symmetric tensor,
3856 * resulting in the symmetric tensor of rank 2 that is given as first argument
3857 * to this function. This operation is the symmetric tensor analogon of a
3858 * matrix-vector multiplication.
3859 *
3860 * This function does the same as SymmetricTensor::operator*().
3861 * It should not be used, however, since the member operator has
3862 * knowledge of the actual data storage format and is at least 2 orders of
3863 * magnitude faster. This function mostly exists for compatibility purposes
3864 * with the general Tensor class.
3865 *
3866 * @relates SymmetricTensor
3867 */
3868 template <typename Number, typename OtherNumber>
3869 DEAL_II_HOST constexpr inline void
3870 double_contract(
3871 SymmetricTensor<2, 1, typename ProductType<Number, OtherNumber>::type> &tmp,
3872 const SymmetricTensor<2, 1, Number> &s,
3873 const SymmetricTensor<4, 1, OtherNumber> &t)
3874 {
3875 tmp[0][0] = t[0][0][0][0] * s[0][0];
3876 }
3877
3878
3879
3880 /**
3881 * Double contraction between a rank-4 and a rank-2 symmetric tensor,
3882 * resulting in the symmetric tensor of rank 2 that is given as first argument
3883 * to this function. This operation is the symmetric tensor analogon of a
3884 * matrix-vector multiplication.
3885 *
3886 * This function does the same as SymmetricTensor::operator*().
3887 * It should not be used, however, since the member operator has
3888 * knowledge of the actual data storage format and is at least 2 orders of
3889 * magnitude faster. This function mostly exists for compatibility purposes
3890 * with the general Tensor class.
3891 *
3892 * @relates SymmetricTensor
3893 */
3894 template <typename Number, typename OtherNumber>
3895 DEAL_II_HOST constexpr inline void
3896 double_contract(
3897 SymmetricTensor<2, 2, typename ProductType<Number, OtherNumber>::type> &tmp,
3898 const SymmetricTensor<4, 2, Number> &t,
3899 const SymmetricTensor<2, 2, OtherNumber> &s)
3900 {
3901 const unsigned int dim = 2;
3902
3903 for (unsigned int i = 0; i < dim; ++i)
3904 for (unsigned int j = i; j < dim; ++j)
3905 tmp[i][j] = t[i][j][0][0] * s[0][0] + t[i][j][1][1] * s[1][1] +
3906 2 * t[i][j][0][1] * s[0][1];
3907 }
3908
3909
3910
3911 /**
3912 * Double contraction between a rank-4 and a rank-2 symmetric tensor,
3913 * resulting in the symmetric tensor of rank 2 that is given as first argument
3914 * to this function. This operation is the symmetric tensor analogon of a
3915 * matrix-vector multiplication.
3916 *
3917 * This function does the same as SymmetricTensor::operator*().
3918 * It should not be used, however, since the member operator has
3919 * knowledge of the actual data storage format and is at least 2 orders of
3920 * magnitude faster. This function mostly exists for compatibility purposes
3921 * with the general Tensor class.
3922 *
3923 * @relates SymmetricTensor
3924 */
3925 template <typename Number, typename OtherNumber>
3926 DEAL_II_HOST constexpr inline void
3927 double_contract(
3928 SymmetricTensor<2, 2, typename ProductType<Number, OtherNumber>::type> &tmp,
3929 const SymmetricTensor<2, 2, Number> &s,
3930 const SymmetricTensor<4, 2, OtherNumber> &t)
3931 {
3932 const unsigned int dim = 2;
3933
3934 for (unsigned int i = 0; i < dim; ++i)
3935 for (unsigned int j = i; j < dim; ++j)
3936 tmp[i][j] = s[0][0] * t[0][0][i][j] * +s[1][1] * t[1][1][i][j] +
3937 2 * s[0][1] * t[0][1][i][j];
3938 }
3939
3940
3941
3942 /**
3943 * Double contraction between a rank-4 and a rank-2 symmetric tensor,
3944 * resulting in the symmetric tensor of rank 2 that is given as first argument
3945 * to this function. This operation is the symmetric tensor analogon of a
3946 * matrix-vector multiplication.
3947 *
3948 * This function does the same as SymmetricTensor::operator*().
3949 * It should not be used, however, since the member operator has
3950 * knowledge of the actual data storage format and is at least 2 orders of
3951 * magnitude faster. This function mostly exists for compatibility purposes
3952 * with the general Tensor class.
3953 *
3954 * @relates SymmetricTensor
3955 */
3956 template <typename Number, typename OtherNumber>
3957 DEAL_II_HOST constexpr inline void
3958 double_contract(
3959 SymmetricTensor<2, 3, typename ProductType<Number, OtherNumber>::type> &tmp,
3960 const SymmetricTensor<4, 3, Number> &t,
3961 const SymmetricTensor<2, 3, OtherNumber> &s)
3962 {
3963 const unsigned int dim = 3;
3964
3965 for (unsigned int i = 0; i < dim; ++i)
3966 for (unsigned int j = i; j < dim; ++j)
3967 tmp[i][j] = t[i][j][0][0] * s[0][0] + t[i][j][1][1] * s[1][1] +
3968 t[i][j][2][2] * s[2][2] + 2 * t[i][j][0][1] * s[0][1] +
3969 2 * t[i][j][0][2] * s[0][2] + 2 * t[i][j][1][2] * s[1][2];
3970 }
3971
3972
3973
3974 /**
3975 * Double contraction between a rank-4 and a rank-2 symmetric tensor,
3976 * resulting in the symmetric tensor of rank 2 that is given as first argument
3977 * to this function. This operation is the symmetric tensor analogon of a
3978 * matrix-vector multiplication.
3979 *
3980 * This function does the same as SymmetricTensor::operator*().
3981 * It should not be used, however, since the member operator has
3982 * knowledge of the actual data storage format and is at least 2 orders of
3983 * magnitude faster. This function mostly exists for compatibility purposes
3984 * with the general Tensor class.
3985 *
3986 * @relates SymmetricTensor
3987 */
3988 template <typename Number, typename OtherNumber>
3989 DEAL_II_HOST constexpr inline void
3990 double_contract(
3991 SymmetricTensor<2, 3, typename ProductType<Number, OtherNumber>::type> &tmp,
3992 const SymmetricTensor<2, 3, Number> &s,
3993 const SymmetricTensor<4, 3, OtherNumber> &t)
3994 {
3995 const unsigned int dim = 3;
3996
3997 for (unsigned int i = 0; i < dim; ++i)
3998 for (unsigned int j = i; j < dim; ++j)
3999 tmp[i][j] = s[0][0] * t[0][0][i][j] + s[1][1] * t[1][1][i][j] +
4000 s[2][2] * t[2][2][i][j] + 2 * s[0][1] * t[0][1][i][j] +
4001 2 * s[0][2] * t[0][2][i][j] + 2 * s[1][2] * t[1][2][i][j];
4002 }
4003
4004
4005
4006 /**
4007 * Multiply a symmetric rank-2 tensor (i.e., a matrix) by a rank-1 tensor
4008 * (i.e., a vector). The result is a rank-1 tensor (i.e., a vector).
4009 *
4010 * @relates SymmetricTensor
4011 */
4012 template <int dim, typename Number, typename OtherNumber>
4013 DEAL_II_HOST constexpr Tensor<1,
4014 dim,
4015 typename ProductType<Number, OtherNumber>::type>
4016 operator*(const SymmetricTensor<2, dim, Number> &src1,
4017 const Tensor<1, dim, OtherNumber> &src2)
4018 {
4019 Tensor<1, dim, typename ProductType<Number, OtherNumber>::type> dest;
4020 for (unsigned int i = 0; i < dim; ++i)
4021 {
4022 dest[i] = src1[i][0] * src2[0];
4023 for (unsigned int j = 1; j < dim; ++j)
4024 dest[i] += src1[i][j] * src2[j];
4025 }
4026 return dest;
4027 }
4028
4029
4030 /**
4031 * Multiply a rank-1 tensor (i.e., a vector) by a symmetric rank-2 tensor
4032 * (i.e., a matrix). The result is a rank-1 tensor (i.e., a vector).
4033 *
4034 * @relates SymmetricTensor
4035 */
4036 template <int dim, typename Number, typename OtherNumber>
4037 DEAL_II_HOST constexpr Tensor<1,
4038 dim,
4039 typename ProductType<Number, OtherNumber>::type>
4040 operator*(const Tensor<1, dim, Number> &src1,
4041 const SymmetricTensor<2, dim, OtherNumber> &src2)
4042 {
4043 // this is easy for symmetric tensors:
4044 return src2 * src1;
4045 }
4046
4047
4048
4049 /**
4050 * The dot product (single contraction) for tensors: Return a tensor of rank
4051 * $(\text{rank}_1 + \text{rank}_2 - 2)$ that is the contraction of the last
4052 * index of a tensor @p src1 of rank @p rank_1 with the first index of a
4053 * tensor @p src2 of rank @p rank_2:
4054 * @f[
4055 * \text{result}_{i_1,\ldots,i_{r1},j_1,\ldots,j_{r2}}
4056 * = \sum_{k}
4057 * \text{left}_{i_1,\ldots,i_{r1}, k}
4058 * \text{right}_{k, j_1,\ldots,j_{r2}}
4059 * @f]
4060 *
4061 * @note As one operand is a Tensor, the multiplication operator only performs a
4062 * contraction over a single pair of indices. This is in contrast to the
4063 * multiplication operator for SymmetricTensor, which does the double
4064 * contraction.
4065 *
4066 * @relates SymmetricTensor
4067 */
4068 template <int rank_1,
4069 int rank_2,
4070 int dim,
4071 typename Number,
4072 typename OtherNumber>
4073 DEAL_II_HOST constexpr DEAL_II_ALWAYS_INLINE
4074 typename Tensor<rank_1 + rank_2 - 2,
4075 dim,
4076 typename ProductType<Number, OtherNumber>::type>::tensor_type
4077 operator*(const Tensor<rank_1, dim, Number> &src1,
4078 const SymmetricTensor<rank_2, dim, OtherNumber> &src2)
4079 {
4080 return src1 * Tensor<rank_2, dim, OtherNumber>(src2);
4081 }
4082
4083
4084
4085 /**
4086 * The dot product (single contraction) for tensors: Return a tensor of rank
4087 * $(\text{rank}_1 + \text{rank}_2 - 2)$ that is the contraction of the last
4088 * index of a tensor @p src1 of rank @p rank_1 with the first index of a
4089 * tensor @p src2 of rank @p rank_2:
4090 * @f[
4091 * \text{result}_{i_1,\ldots,i_{r1},j_1,\ldots,j_{r2}}
4092 * = \sum_{k}
4093 * \text{left}_{i_1,\ldots,i_{r1}, k}
4094 * \text{right}_{k, j_1,\ldots,j_{r2}}
4095 * @f]
4096 *
4097 * @note As one operand is a Tensor, the multiplication operator only performs a
4098 * contraction over a single pair of indices. This is in contrast to the
4099 * multiplication operator for SymmetricTensor, which does the double
4100 * contraction.
4101 *
4102 * @relates SymmetricTensor
4103 */
4104 template <int rank_1,
4105 int rank_2,
4106 int dim,
4107 typename Number,
4108 typename OtherNumber>
4109 DEAL_II_HOST constexpr DEAL_II_ALWAYS_INLINE
4110 typename Tensor<rank_1 + rank_2 - 2,
4111 dim,
4112 typename ProductType<Number, OtherNumber>::type>::tensor_type
4113 operator*(const SymmetricTensor<rank_1, dim, Number> &src1,
4114 const Tensor<rank_2, dim, OtherNumber> &src2)
4115 {
4116 return Tensor<rank_1, dim, Number>(src1) * src2;
4117 }
4118
4119
4120
4121 /**
4122 * Output operator for symmetric tensors of rank 2. Print the elements
4123 * consecutively, with a space in between, two spaces between rank 1
4124 * subtensors, three between rank 2 and so on. No special amends are made to
4125 * represents the symmetry in the output, for example by outputting only the
4126 * unique entries.
4127 *
4128 * @relates SymmetricTensor
4129 */
4130 template <int dim, typename Number>
4131 inline std::ostream &
4132 operator<<(std::ostream &out, const SymmetricTensor<2, dim, Number> &t)
4133 {
4134 // make our lives a bit simpler by outputting
4135 // the tensor through the operator for the
4136 // general Tensor class
4137 Tensor<2, dim, Number> tt;
4138
4139 for (unsigned int i = 0; i < dim; ++i)
4140 for (unsigned int j = 0; j < dim; ++j)
4141 tt[i][j] = t[i][j];
4142
4143 return out << tt;
4144 }
4145
4146
4147
4148 /**
4149 * Output operator for symmetric tensors of rank 4. Print the elements
4150 * consecutively, with a space in between, two spaces between rank 1
4151 * subtensors, three between rank 2 and so on. No special amends are made to
4152 * represents the symmetry in the output, for example by outputting only the
4153 * unique entries.
4154 *
4155 * @relates SymmetricTensor
4156 */
4157 template <int dim, typename Number>
4158 inline std::ostream &
4159 operator<<(std::ostream &out, const SymmetricTensor<4, dim, Number> &t)
4160 {
4161 // make our lives a bit simpler by outputting
4162 // the tensor through the operator for the
4163 // general Tensor class
4164 Tensor<4, dim, Number> tt;
4165
4166 for (unsigned int i = 0; i < dim; ++i)
4167 for (unsigned int j = 0; j < dim; ++j)
4168 for (unsigned int k = 0; k < dim; ++k)
4169 for (unsigned int l = 0; l < dim; ++l)
4170 tt[i][j][k][l] = t[i][j][k][l];
4171
4172 return out << tt;
4173 }
4174
4175
4176 DEAL_II_NAMESPACE_CLOSE
4177
4178 #endif