Debian Codegraph @

include/deal.II/base/symmetric_tensor.templates.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2017 - 2024 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15 #ifndef dealii_symmetric_tensor_templates_h
16 #define dealii_symmetric_tensor_templates_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/exceptions.h>
22 #include <deal.II/base/symmetric_tensor.h>
23
24 #include <deal.II/differentiation/ad.h>
25
26 #include <deal.II/physics/transformations.h>
27
28 #include <array>
29 #include <limits>
30
31 DEAL_II_NAMESPACE_OPEN
32
33
34
35 template <typename Number>
36 std::array<Number, 1>
37 eigenvalues(const SymmetricTensor<2, 1, Number> &T)
38 {
39 return {{T[0][0]}};
40 }
41
42
43
44 template <typename Number>
45 std::array<Number, 2>
46 eigenvalues(const SymmetricTensor<2, 2, Number> &T)
47 {
48 // Make things work with AD types
49 using std::sqrt;
50
51 const Number upp_tri_sq = T[0][1] * T[0][1];
52 if (upp_tri_sq == internal::NumberType<Number>::value(0.0))
53 {
54 // The tensor is diagonal
55 std::array<Number, 2> eig_vals = {{T[0][0], T[1][1]}};
56
57 // Sort from largest to smallest.
58 std::sort(eig_vals.begin(), eig_vals.end(), std::greater<Number>());
59 return eig_vals;
60 }
61 else
62 {
63 const Number tr_T = trace(T);
64 const Number det_T = determinant(T);
65 const Number descrim = tr_T * tr_T - 4.0 * det_T;
66 Assert(
67 descrim > internal::NumberType<Number>::value(0.0),
68 ExcMessage(
69 "The roots of the characteristic polynomial are complex valued."));
70 const Number sqrt_desc = sqrt(descrim);
71
72 const std::array<Number, 2> eig_vals = {
73 {internal::NumberType<Number>::value(0.5 * (tr_T + sqrt_desc)),
74 internal::NumberType<Number>::value(0.5 * (tr_T - sqrt_desc))}};
75 Assert(eig_vals[0] >= eig_vals[1],
76 ExcMessage("The eigenvalue ordering is incorrect."));
77 return eig_vals;
78 }
79 }
80
81
82
83 template <typename Number>
84 std::array<Number, 3>
85 eigenvalues(const SymmetricTensor<2, 3, Number> &T)
86 {
87 // Make things work with AD types
88 using std::acos;
89 using std::cos;
90 using std::sqrt;
91
92 const Number upp_tri_sq =
93 T[0][1] * T[0][1] + T[0][2] * T[0][2] + T[1][2] * T[1][2];
94 if (upp_tri_sq == internal::NumberType<Number>::value(0.0))
95 {
96 // The tensor is diagonal
97 std::array<Number, 3> eig_vals = {{T[0][0], T[1][1], T[2][2]}};
98
99 // Sort from largest to smallest.
100 std::sort(eig_vals.begin(), eig_vals.end(), std::greater<Number>());
101 return eig_vals;
102 }
103 else
104 {
105 // Perform an affine change to T, and solve a different
106 // characteristic equation that has a trigonometric solution.
107 // Decompose T = p*B + q*I , and set q = tr(T)/3
108 // and p = (tr((T - q.I)^{2})/6)^{1/2} . Then solve the equation
109 // 0 = det(\lambda*I - B) = \lambda^{3} - 3*\lambda - det(B)
110 // which has the solution
111 // \lambda = 2*cos(1/3 * acos(det(B)/2) +2/3*pi*k ); k = 0,1,2
112 // when substituting \lambda = 2.cos(theta) and using trig identities.
113 const Number tr_T = trace(T);
114 const Number q = tr_T / 3.0;
115 const Number tmp1 = (T[0][0] - q) * (T[0][0] - q) +
116 (T[1][1] - q) * (T[1][1] - q) +
117 (T[2][2] - q) * (T[2][2] - q) + 2.0 * upp_tri_sq;
118 const Number p = sqrt(tmp1 / 6.0);
119 const SymmetricTensor<2, 3, Number> B =
120 Number(1.0 / p) * (T - q * unit_symmetric_tensor<3, Number>());
121 const Number tmp_2 = determinant(B) / 2.0;
122
123 // The value of tmp_2 should be within [-1,1], however
124 // floating point errors might place it slightly outside
125 // this range. It is therefore necessary to correct for it.
126 // Note: The three results in the conditional may lead to different
127 // number types when using Sacado numbers, so we cast them when
128 // necessary to a consistent result type.
129 const Number phi =
130 (tmp_2 <= -1.0 ?
131 internal::NumberType<Number>::value(numbers::PI / 3.0) :
132 (tmp_2 >= 1.0 ?
133 internal::NumberType<Number>::value(0.0) :
134 internal::NumberType<Number>::value(acos(tmp_2) / 3.0)));
135
136 // Due to the trigonometric solution, the computed eigenvalues
137 // should be predictably in the order eig1 >= eig2 >= eig3...
138 std::array<Number, 3> eig_vals = {
139 {static_cast<Number>(q + 2.0 * p * cos(phi)),
140 static_cast<Number>(0.0),
141 static_cast<Number>(q +
142 2.0 * p * cos(phi + (2.0 / 3.0 * numbers::PI)))}};
143 // Use the identity tr(T) = eig1 + eig2 + eig3
144 eig_vals[1] = tr_T - eig_vals[0] - eig_vals[2];
145
146 // ... however, when equal roots exist then floating point
147 // errors may make this no longer be the case.
148 // Sort from largest to smallest.
149 std::sort(eig_vals.begin(), eig_vals.end(), std::greater<Number>());
150
151 return eig_vals;
152 }
153 }
154
155
156
157 namespace internal
158 {
159 namespace SymmetricTensorImplementation
160 {
161 template <int dim, typename Number>
162 void
163 tridiagonalize(const dealii::SymmetricTensor<2, dim, Number> &A,
164 dealii::Tensor<2, dim, Number> &Q,
165 std::array<Number, dim> &d,
166 std::array<Number, dim - 1> &e)
167 {
168 // Make things work with AD types
169 using std::sqrt;
170
171 // Create some intermediate storage
172 Number h, g, omega_inv, K, f;
173
174 // Initialize the transformation matrix as the
175 // identity tensor
176 Q = static_cast<Tensor<2, dim, Number>>(
177 dealii::unit_symmetric_tensor<dim, Number>());
178
179 // Make the first row and column to be of the
180 // desired form
181 h = 0.0;
182 for (int i = 1; i < dim; ++i)
183 h += A[0][i] * A[0][i];
184
185 g = 0.0;
186 if (A[0][1] > 0.0)
187 g = -sqrt(h);
188 else
189 g = sqrt(h);
190 e[0] = g;
191
192 std::array<Number, dim> u;
193 for (int i = 1; i < dim; ++i)
194 {
195 u[i] = A[0][i];
196 if (i == 1)
197 u[i] -= g;
198 }
199
200 std::array<Number, dim> q;
201 const Number omega = h - g * A[0][1];
202 if (omega > 0.0)
203 {
204 omega_inv = 1.0 / omega;
205 K = 0.0;
206 for (int i = 1; i < dim; ++i)
207 {
208 f = 0.0;
209 for (int j = 1; j < dim; ++j)
210 f += A[i][j] * u[j];
211 q[i] = omega_inv * f;
212 K += u[i] * f;
213 }
214 K *= 0.5 * omega_inv * omega_inv;
215
216 for (int i = 1; i < dim; ++i)
217 q[i] = q[i] - K * u[i];
218
219 d[0] = A[0][0];
220 for (int i = 1; i < dim; ++i)
221 d[i] = A[i][i] - 2.0 * q[i] * u[i];
222
223 // Store inverse Householder transformation
224 // in Q
225 for (int j = 1; j < dim; ++j)
226 {
227 f = omega_inv * u[j];
228 for (int i = 1; i < dim; ++i)
229 Q[i][j] = Q[i][j] - f * u[i];
230 }
231
232 // For dim = 3: Calculate updated A[1][2] and
233 // store it in e[1]
234 for (int i = 1; i < dim - 1; ++i)
235 e[i] = A[i][i + 1] - q[i] * u[i + 1] - u[i] * q[i + 1];
236 }
237 else
238 {
239 for (unsigned int i = 0; i < dim; ++i)
240 d[i] = A[i][i];
241
242 // For dim = 3:
243 for (int i = 1; i < dim - 1; ++i)
244 e[i] = A[i][i + 1];
245 }
246 }
247
248
249
250 template <int dim, typename Number>
251 std::array<std::pair<Number, Tensor<1, dim, Number>>, dim>
252 ql_implicit_shifts(const dealii::SymmetricTensor<2, dim, Number> &A)
253 {
254 // Make things work with AD types
255 using std::fabs;
256 using std::sqrt;
257
258 static_assert(
259 numbers::NumberTraits<Number>::is_complex == false,
260 "This implementation of the QL implicit shift algorithm does "
261 "not support complex numbers");
262
263 // Transform A to real tridiagonal form by the Householder method:
264 // The orthogonal matrix effecting the transformation
265 // this will ultimately store the eigenvectors
266 dealii::Tensor<2, dim, Number> Q;
267 // The diagonal elements of the tridiagonal matrix;
268 // this will ultimately store the eigenvalues
269 std::array<Number, dim> w;
270 // The off-diagonal elements of the tridiagonal
271 std::array<Number, dim - 1> ee;
272 tridiagonalize<dim, Number>(A, Q, w, ee);
273
274 // Number of iterations
275 const unsigned int max_n_it = 30;
276
277 // Transfer the off-diagonal entries to an auxiliary array
278 // The third element is used only as temporary workspace
279 std::array<Number, dim> e;
280 for (unsigned int i = 0; i < dim - 1; ++i)
281 e[i] = ee[i];
282
283 // Create some intermediate storage
284 Number g, r, p, f, b, s, c, t;
285
286 // Loop over all off-diagonal elements
287 for (int l = 0; l < dim - 1; ++l)
288 {
289 for (unsigned int it = 0; it <= max_n_it; ++it)
290 {
291 // Check for convergence and exit iteration loop
292 // if the off-diagonal element e[l] is zero
293 int m = l;
294 for (; m <= dim - 2; ++m)
295 {
296 g = fabs(w[m]) + fabs(w[m + 1]);
297 if (fabs(e[m]) + g == g)
298 break;
299 }
300 if (m == l)
301 break;
302
303 // Throw if no convergence is achieved within a
304 // stipulated number of iterations
305 if (it == max_n_it)
306 {
307 AssertThrow(
308 false,
309 ExcMessage(
310 "No convergence in iterative QL eigenvector algorithm."));
311 return std::array<std::pair<Number, Tensor<1, dim, Number>>,
312 dim>();
313 }
314
315 // Calculate the shift..
316 g = (w[l + 1] - w[l]) / (e[l] + e[l]);
317 r = sqrt(g * g + 1.0);
318 // .. and then compute g = d_m - k_s for the
319 // plane rotation (Press2007a eq 11.4.22)
320 if (g > 0.0)
321 g = w[m] - w[l] + e[l] / (g + r);
322 else
323 g = w[m] - w[l] + e[l] / (g - r);
324
325 // Perform plane rotation, as is done in the
326 // standard QL algorithm, followed by Givens
327 // rotations to recover the tridiagonal form
328 s = c = 1.0;
329 p = 0.0;
330 for (int i = m - 1; i >= l; i--)
331 {
332 f = s * e[i];
333 b = c * e[i];
334
335 // Branch to recover from underflow
336 if (fabs(f) > fabs(g))
337 {
338 c = g / f;
339 r = sqrt(c * c + 1.0);
340 e[i + 1] = f * r;
341 c *= (s = 1.0 / r);
342 }
343 else
344 {
345 s = f / g;
346 r = sqrt(s * s + 1.0);
347 e[i + 1] = g * r;
348 s *= (c = 1.0 / r);
349 }
350
351 g = w[i + 1] - p;
352 r = (w[i] - g) * s + 2.0 * c * b;
353 p = s * r;
354 w[i + 1] = g + p;
355 g = c * r - b;
356
357 // Form the eigenvectors
358 for (unsigned int k = 0; k < dim; ++k)
359 {
360 t = Q[k][i + 1];
361 Q[k][i + 1] = s * Q[k][i] + c * t;
362 Q[k][i] = c * Q[k][i] - s * t;
363 }
364 }
365 w[l] -= p;
366 e[l] = g;
367 e[m] = 0.0;
368 }
369 }
370
371 // Structure the data to be outputted
372 std::array<std::pair<Number, Tensor<1, dim, Number>>, dim> eig_vals_vecs;
373 for (unsigned int e = 0; e < dim; ++e)
374 {
375 eig_vals_vecs[e].first = w[e];
376
377 // The column "e" of Q contains the non-normalized
378 // eigenvector associated with the eigenvalue "e"
379 for (unsigned int a = 0; a < dim; ++a)
380 {
381 eig_vals_vecs[e].second[a] = Q[a][e];
382 }
383
384 // Normalize
385 Assert(eig_vals_vecs[e].second.norm() != 0.0, ExcDivideByZero());
386 eig_vals_vecs[e].second /= eig_vals_vecs[e].second.norm();
387 }
388 return eig_vals_vecs;
389 }
390
391
392
393 template <int dim, typename Number>
394 std::array<std::pair<Number, Tensor<1, dim, Number>>, dim>
395 jacobi(dealii::SymmetricTensor<2, dim, Number> A)
396 {
397 static_assert(numbers::NumberTraits<Number>::is_complex == false,
398 "This implementation of the Jacobi algorithm does "
399 "not support complex numbers");
400
401 // Make things work with AD types
402 using std::fabs;
403 using std::sqrt;
404
405 // Sums of diagonal resp. off-diagonal elements
406 Number sd, so;
407 // sin(phi), cos(phi), tan(phi) and temporary storage
408 Number s, c, t;
409 // More temporary storage
410 Number g, h, z, theta;
411 // Threshold value
412 Number thresh;
413
414 // Initialize the transformation matrix as the
415 // identity tensor
416 dealii::Tensor<2, dim, Number> Q(
417 dealii::unit_symmetric_tensor<dim, Number>());
418
419 // The diagonal elements of the tridiagonal matrix;
420 // this will ultimately store the eigenvalues
421 std::array<Number, dim> w;
422 for (unsigned int i = 0; i < dim; ++i)
423 w[i] = A[i][i];
424
425 // Calculate (tr(A))^{2}
426 sd = trace(A);
427 sd *= sd;
428
429 // Number of iterations
430 const unsigned int max_n_it = 50;
431 for (unsigned int it = 0; it <= max_n_it; ++it)
432 {
433 // Test for convergence
434 so = 0.0;
435 for (unsigned int p = 0; p < dim; ++p)
436 for (int q = p + 1; q < dim; ++q)
437 so += fabs(A[p][q]);
438 if (so == 0.0)
439 break;
440
441 // Throw if no convergence is achieved within a
442 // stipulated number of iterations
443 if (it == max_n_it)
444 {
445 AssertThrow(
446 false,
447 ExcMessage(
448 "No convergence in iterative Jacobi eigenvector algorithm."));
449 return std::array<std::pair<Number, Tensor<1, dim, Number>>,
450 dim>();
451 }
452
453 // Compute threshold value which dictates whether or
454 // not a Jacobi rotation is performed
455 const unsigned int n_it_skip = 4;
456 if (it < n_it_skip)
457 thresh = 0.2 * so / (dim * dim);
458 else
459 thresh = 0.0;
460
461 // Perform sweep
462 for (unsigned int p = 0; p < dim; ++p)
463 for (unsigned int q = p + 1; q < dim; ++q)
464 {
465 g = 100.0 * fabs(A[p][q]);
466
467 // After a given number of iterations the
468 // rotation is skipped if the off-diagonal
469 // element is small
470 if (it > n_it_skip && fabs(w[p]) + g == fabs(w[p]) &&
471 fabs(w[q]) + g == fabs(w[q]))
472 {
473 A[p][q] = 0.0;
474 }
475 else if (fabs(A[p][q]) > thresh)
476 {
477 // Calculate Jacobi transformation
478 h = w[q] - w[p];
479
480 // Compute surrogate for angle theta resulting from
481 // angle transformation and subsequent smallest solution
482 // of quadratic equation
483 if (fabs(h) + g == fabs(h))
484 {
485 // Prevent overflow for large theta^2. This computation
486 // is the algebraic equivalent of t = 1/(2*theta).
487 t = A[p][q] / h;
488 }
489 else
490 {
491 theta = 0.5 * h / A[p][q];
492 if (theta < 0.0)
493 t = -1.0 / (sqrt(1.0 + theta * theta) - theta);
494 else
495 t = 1.0 / (sqrt(1.0 + theta * theta) + theta);
496 }
497
498 // Compute trigonometric functions for rotation
499 // in such a way as to prevent overflow for
500 // large theta.
501 c = 1.0 / sqrt(1.0 + t * t);
502 s = t * c;
503 z = t * A[p][q];
504
505 // Apply Jacobi transformation...
506 A[p][q] = 0.0;
507 w[p] -= z;
508 w[q] += z;
509 // ... by executing the various rotations in sequence
510 for (unsigned int r = 0; r < p; ++r)
511 {
512 t = A[r][p];
513 A[r][p] = c * t - s * A[r][q];
514 A[r][q] = s * t + c * A[r][q];
515 }
516 for (unsigned int r = p + 1; r < q; ++r)
517 {
518 t = A[p][r];
519 A[p][r] = c * t - s * A[r][q];
520 A[r][q] = s * t + c * A[r][q];
521 }
522 for (unsigned int r = q + 1; r < dim; ++r)
523 {
524 t = A[p][r];
525 A[p][r] = c * t - s * A[q][r];
526 A[q][r] = s * t + c * A[q][r];
527 }
528
529 // Update the eigenvectors
530 for (unsigned int r = 0; r < dim; ++r)
531 {
532 t = Q[r][p];
533 Q[r][p] = c * t - s * Q[r][q];
534 Q[r][q] = s * t + c * Q[r][q];
535 }
536 }
537 }
538 }
539
540 // Structure the data to be outputted
541 std::array<std::pair<Number, Tensor<1, dim, Number>>, dim> eig_vals_vecs;
542 for (unsigned int e = 0; e < dim; ++e)
543 {
544 eig_vals_vecs[e].first = w[e];
545
546 // The column "e" of Q contains the non-normalized
547 // eigenvector associated with the eigenvalue "e"
548 for (unsigned int a = 0; a < dim; ++a)
549 {
550 eig_vals_vecs[e].second[a] = Q[a][e];
551 }
552
553 // Normalize
554 Assert(eig_vals_vecs[e].second.norm() != 0.0, ExcDivideByZero());
555 eig_vals_vecs[e].second /= eig_vals_vecs[e].second.norm();
556 }
557 return eig_vals_vecs;
558 }
559
560
561
562 template <typename Number>
563 std::array<std::pair<Number, Tensor<1, 2, Number>>, 2>
564 hybrid(const dealii::SymmetricTensor<2, 2, Number> &A)
565 {
566 static_assert(numbers::NumberTraits<Number>::is_complex == false,
567 "This implementation of the 2d Hybrid algorithm does "
568 "not support complex numbers");
569
570 // Make things work with AD types
571 using std::fabs;
572
573 const unsigned int dim = 2;
574
575 // Calculate eigenvalues
576 const std::array<Number, dim> w = eigenvalues(A);
577
578 std::array<std::pair<Number, Tensor<1, dim, Number>>, dim> eig_vals_vecs;
579
580 Number t, u; // Intermediate storage
581 t = fabs(w[0]);
582 for (unsigned int i = 1; i < dim; ++i)
583 {
584 u = fabs(w[i]);
585 if (u > t)
586 t = u;
587 }
588
589 if (t < 1.0)
590 u = t;
591 else
592 u = t * t;
593
594 // Estimated maximum roundoff error
595 const Number error =
596 256.0 * std::numeric_limits<double>::epsilon() * u * u;
597
598 // Store eigenvalues
599 eig_vals_vecs[0].first = w[0];
600 eig_vals_vecs[1].first = w[1];
601
602 // Compute eigenvectors
603 // http://www.math.harvard.edu/archive/21b_fall_04/exhibits/2dmatrices/
604 // https://math.stackexchange.com/a/1548616
605 if (A[1][0] != 0.0)
606 {
607 // First eigenvector
608 eig_vals_vecs[0].second[0] = w[0] - A[1][1];
609 eig_vals_vecs[0].second[1] = A[1][0];
610
611 // Second eigenvector
612 eig_vals_vecs[1].second[0] = w[1] - A[1][1];
613 eig_vals_vecs[1].second[1] = A[1][0];
614 }
615 else
616 {
617 // First eigenvector
618 eig_vals_vecs[0].second[0] = w[0];
619 eig_vals_vecs[0].second[1] = 0.0;
620
621 // Second eigenvector
622 eig_vals_vecs[1].second[0] = 0.0;
623 eig_vals_vecs[1].second[1] = w[1];
624 }
625 // Normalize
626 eig_vals_vecs[0].second /= eig_vals_vecs[0].second.norm();
627 eig_vals_vecs[1].second /= eig_vals_vecs[1].second.norm();
628
629 // If vectors are nearly linearly dependent, or if there might have
630 // been large cancellations in the calculation of A[i][i] - w[0], fall
631 // back to QL algorithm
632 if (eig_vals_vecs[0].second * eig_vals_vecs[1].second > error)
633 {
634 return ql_implicit_shifts(A);
635 }
636
637 return eig_vals_vecs;
638 }
639
640
641
642 template <typename Number>
643 std::array<std::pair<Number, Tensor<1, 3, Number>>, 3>
644 hybrid(const dealii::SymmetricTensor<2, 3, Number> &A)
645 {
646 static_assert(numbers::NumberTraits<Number>::is_complex == false,
647 "This implementation of the 3d Hybrid algorithm does "
648 "not support complex numbers");
649
650 // Make things work with AD types
651 using std::fabs;
652 using std::sqrt;
653
654 const unsigned int dim = 3;
655 Number norm; // Squared norm or inverse norm of current eigenvector
656 Number t, u; // Intermediate storage
657
658 // Calculate eigenvalues
659 const std::array<Number, dim> w = eigenvalues(A);
660
661 t = fabs(w[0]);
662 for (unsigned int i = 1; i < dim; ++i)
663 {
664 u = fabs(w[i]);
665 if (u > t)
666 t = u;
667 }
668
669 if (t < 1.0)
670 u = t;
671 else
672 u = t * t;
673
674 // Estimated maximum roundoff error
675 const Number error =
676 256.0 * std::numeric_limits<double>::epsilon() * u * u;
677
678 // Initialize the transformation matrix as the
679 // identity tensor
680 dealii::Tensor<2, dim, Number> Q;
681 Q[0][1] = A[0][1] * A[1][2] - A[0][2] * A[1][1];
682 Q[1][1] = A[0][2] * A[0][1] - A[1][2] * A[0][0];
683 Q[2][1] = A[0][1] * A[0][1];
684
685 // Calculate first eigenvector by the formula
686 // v[0] = (A - w[0]).e1 x (A - w[0]).e2
687 Q[0][0] = Q[0][1] + A[0][2] * w[0];
688 Q[1][0] = Q[1][1] + A[1][2] * w[0];
689 Q[2][0] = (A[0][0] - w[0]) * (A[1][1] - w[0]) - Q[2][1];
690 norm = Q[0][0] * Q[0][0] + Q[1][0] * Q[1][0] + Q[2][0] * Q[2][0];
691
692 // If vectors are nearly linearly dependent, or if there might have
693 // been large cancellations in the calculation of A[i][i] - w[0], fall
694 // back to QL algorithm
695 // Note that this simultaneously ensures that multiple eigenvalues do
696 // not cause problems: If w[0] = w[1], then A - w[0] * I has rank 1,
697 // i.e. all columns of A - w[0] * I are linearly dependent.
698 if (norm <= error)
699 {
700 return ql_implicit_shifts(A);
701 }
702 else // This is the standard branch
703 {
704 norm = sqrt(1.0 / norm);
705 for (unsigned j = 0; j < dim; ++j)
706 Q[j][0] = Q[j][0] * norm;
707 }
708
709 // Calculate second eigenvector by the formula
710 // v[1] = (A - w[1]).e1 x (A - w[1]).e2
711 Q[0][1] = Q[0][1] + A[0][2] * w[1];
712 Q[1][1] = Q[1][1] + A[1][2] * w[1];
713 Q[2][1] = (A[0][0] - w[1]) * (A[1][1] - w[1]) - Q[2][1];
714 norm = Q[0][1] * Q[0][1] + Q[1][1] * Q[1][1] + Q[2][1] * Q[2][1];
715 if (norm <= error)
716 {
717 return ql_implicit_shifts(A);
718 }
719 else
720 {
721 norm = sqrt(1.0 / norm);
722 for (unsigned int j = 0; j < dim; ++j)
723 Q[j][1] = Q[j][1] * norm;
724 }
725
726 // Calculate third eigenvector according to
727 // v[2] = v[0] x v[1]
728 Q[0][2] = Q[1][0] * Q[2][1] - Q[2][0] * Q[1][1];
729 Q[1][2] = Q[2][0] * Q[0][1] - Q[0][0] * Q[2][1];
730 Q[2][2] = Q[0][0] * Q[1][1] - Q[1][0] * Q[0][1];
731
732 // Structure the data to be outputted
733 std::array<std::pair<Number, Tensor<1, dim, Number>>, dim> eig_vals_vecs;
734 for (unsigned int e = 0; e < dim; ++e)
735 {
736 eig_vals_vecs[e].first = w[e];
737
738 // The column "e" of Q contains the non-normalized
739 // eigenvector associated with the eigenvalue "e"
740 for (unsigned int a = 0; a < dim; ++a)
741 {
742 eig_vals_vecs[e].second[a] = Q[a][e];
743 }
744
745 // Normalize
746 Assert(eig_vals_vecs[e].second.norm() != 0.0, ExcDivideByZero());
747 eig_vals_vecs[e].second /= eig_vals_vecs[e].second.norm();
748 }
749 return eig_vals_vecs;
750 }
751
752
753 template <typename Number>
754 Tensor<2, 1, Number>
755 dediagonalize_tensor(const dealii::SymmetricTensor<2, 1, Number> &T,
756 const double /*rotation_angle*/,
757 const unsigned int /*axis*/ = 0)
758 {
759 AssertThrow(false, ExcNotImplemented());
760 return Tensor<2, 1, Number>({{T[0][0]}});
761 }
762
763
764 template <typename Number>
765 Tensor<2, 2, Number>
766 dediagonalize_tensor(const dealii::SymmetricTensor<2, 2, Number> &T,
767 const double rotation_angle,
768 const unsigned int /*axis*/ = 0)
769 {
770 const Tensor<2, 2> R =
771 dealii::Physics::Transformations::Rotations::rotation_matrix_2d(
772 rotation_angle);
773 return R * T;
774 }
775
776
777 template <typename Number>
778 Tensor<2, 3, Number>
779 dediagonalize_tensor(const dealii::SymmetricTensor<2, 3, Number> &T,
780 const double rotation_angle,
781 const unsigned int axis = 0)
782 {
783 AssertIndexRange(axis, 3);
784
785 Tensor<2, 3> R;
786 switch (axis)
787 {
788 case (0):
789 R = dealii::Physics::Transformations::Rotations::rotation_matrix_3d(
790 Tensor<1, 3>({1., 0., 0.}), rotation_angle);
791 break;
792 case (1):
793 R = dealii::Physics::Transformations::Rotations::rotation_matrix_3d(
794 Tensor<1, 3>({0., 1., 0.}), rotation_angle);
795 break;
796 case (2):
797 R = dealii::Physics::Transformations::Rotations::rotation_matrix_3d(
798 Tensor<1, 3>({0., 0., 1.}), rotation_angle);
799 break;
800 default:
801 AssertThrow(false, ExcNotImplemented());
802 break;
803 }
804 return R * T;
805 }
806
807
808 template <typename Number>
809 std::array<std::pair<Number, Tensor<1, 1, Number>>, 1>
810 perform_eigenvector_decomposition(
811 const SymmetricTensor<2, 1, Number> &T,
812 const SymmetricTensorEigenvectorMethod /*method*/)
813 {
814 return {{std::make_pair(T[0][0], Tensor<1, 1, Number>({1.0}))}};
815 }
816
817
818 template <int dim, typename Number>
819 std::array<std::pair<Number, Tensor<1, dim, Number>>, dim>
820 perform_eigenvector_decomposition(
821 const SymmetricTensor<2, dim, Number> &T,
822 const SymmetricTensorEigenvectorMethod method)
823 {
824 switch (method)
825 {
826 case SymmetricTensorEigenvectorMethod::hybrid:
827 return internal::SymmetricTensorImplementation::hybrid(T);
828 break;
829 case SymmetricTensorEigenvectorMethod::ql_implicit_shifts:
830 return internal::SymmetricTensorImplementation::ql_implicit_shifts(
831 T);
832 break;
833 case SymmetricTensorEigenvectorMethod::jacobi:
834 return internal::SymmetricTensorImplementation::jacobi(T);
835 break;
836 default:
837 break;
838 }
839
840 AssertThrow(false, ExcNotImplemented());
841 return std::array<std::pair<Number, Tensor<1, dim, Number>>, dim>();
842 }
843
844
845 } // namespace SymmetricTensorImplementation
846 } // namespace internal
847
848
849
850 template <int dim, typename Number>
851 std::array<std::pair<Number, Tensor<1, dim, Number>>, dim>
852 eigenvectors(const SymmetricTensor<2, dim, Number> &T,
853 const SymmetricTensorEigenvectorMethod method)
854 {
855 // Not much to do when there's only a single entry
856 if (dim == 1)
857 return internal::SymmetricTensorImplementation::
858 perform_eigenvector_decomposition(T, method);
859
860 std::array<std::pair<Number, Tensor<1, dim, Number>>, dim> eig_vals_vecs;
861
862 if (Differentiation::AD::is_ad_number<Number>::value && dim > 1)
863 {
864 // If the tensor is diagonal, then we have a bit on an issue when using
865 // auto-differentiable numbers. The reason for this is that all of the
866 // algorithms have shortcuts by which to return result in this case.
867 // This artificially decouples the eigenvalues/vectors, which upon
868 // differentiation leads to the wrong result (each is, incorrectly,
869 // insensitive with respect to the other). To work around this manipulate
870 // tensor @p T in an objective manner: through an infinitesimal rotation we
871 // make it non-diagonal (although we introduce some numerical error).
872 bool is_diagonal = true;
873 for (unsigned int i = 0; i < dim; ++i)
874 for (unsigned int j = i + 1; j < dim; ++j)
875 if (T[i][j] != 0.0)
876 {
877 is_diagonal = false;
878 break;
879 }
880
881 // If our tensor is not diagonal, then just carry on as per usual.
882 if (!is_diagonal)
883 eig_vals_vecs = internal::SymmetricTensorImplementation::
884 perform_eigenvector_decomposition(T, method);
885 else
886 {
887 Assert(
888 method != SymmetricTensorEigenvectorMethod::hybrid,
889 ExcMessage(
890 "The hybrid method cannot be used with auto-differentiable numbers "
891 "when the tensor upon which an eigen-decomposition is being performed "
892 "is diagonal. This is because the hybrid method immediately assumes "
893 "the values of the eigenvectors (since the characteristic polynomial) "
894 "is not solved, and therefore the sensitivity of the eigenvalues with "
895 "respect to one another is not resolved."));
896
897 // These parameters are heuristicaly chosen through "rigorous"
898 // eye-ball analysis of the errors of tests based on
899 // ad-common-tests/symmetric_tensor_functions_03.h. This checks the
900 // first and second derivatives of the representation of a Neo-Hookean
901 // material described by an Ogden-type model (i.e. using an
902 // eigen-decomposition of the right Cauchy-Green tensor). Using this
903 // comparison between the well-understood result expected from the
904 // Neo-Hookean model and its Ogden equivalent, these parameters are a
905 // first approximation to those required to collectively minimize
906 // error in the energy values, first and second derivatives. What's
907 // apparent is that all AD numbers and eigen-decomposition algorithms
908 // are not made equal!
909 double sf = 1.0;
910 if (Differentiation::AD::is_taped_ad_number<Number>::value)
911 {
912 // ADOL-C taped
913 if (method ==
914 SymmetricTensorEigenvectorMethod::ql_implicit_shifts)
915 sf = 2e11;
916 else if (method == SymmetricTensorEigenvectorMethod::jacobi)
917 sf = (dim == 2 ? 1e6 : 1e9);
918 else
919 AssertThrow(false, ExcNotImplemented());
920 }
921 else if (Differentiation::AD::is_sacado_rad_number<Number>::value)
922 {
923 // Sacado::Rad
924 if (method ==
925 SymmetricTensorEigenvectorMethod::ql_implicit_shifts)
926 sf = (dim == 2 ? 1e8 : 1e9);
927 else if (method == SymmetricTensorEigenvectorMethod::jacobi)
928 sf = (dim == 2 ? 1e8 : 1e9);
929 else
930 AssertThrow(false, ExcNotImplemented());
931 }
932 else
933 {
934 // Everything else
935 Assert(Differentiation::AD::is_tapeless_ad_number<Number>::value,
936 ExcInternalError());
937 Assert(
938 Differentiation::AD::is_sacado_dfad_number<Number>::value ||
939 Differentiation::AD::is_adolc_tapeless_number<Number>::value,
940 ExcInternalError());
941
942 if (method ==
943 SymmetricTensorEigenvectorMethod::ql_implicit_shifts)
944 sf = (dim == 2 ? 1e7 : 2.5e7);
945 else if (method == SymmetricTensorEigenvectorMethod::jacobi)
946 sf = (dim == 2 ? 1e2 : 1e7);
947 else
948 AssertThrow(false, ExcNotImplemented());
949 }
950
951 using scalar_type =
952 typename Differentiation::AD::ADNumberTraits<Number>::scalar_type;
953 const double delta = sf * std::numeric_limits<scalar_type>::epsilon();
954 const double rotation_angle = delta * numbers::PI / 180.0;
955
956 if (dim == 2)
957 {
958 const Tensor<2, dim, Number> T_prime_ns =
959 internal::SymmetricTensorImplementation::dediagonalize_tensor(
960 T, rotation_angle);
961
962 // We can't symmetrize the tensor, otherwise the sensitivities
963 // cancel out. So we take the upper triangle as an approximation
964 // instead.
965 // TODO[JPP]: Perform the eigen-decomposition on the non-symmetric
966 // T_prime_ns. This is, however, nontrivial to
967 // implement in this context. See:
968 // http://www.alglib.net/eigen/nonsymmetric/nonsymmetricevd.php
969 // https://groups.google.com/forum/#!topic/stan-users/QJe1TNioiyg
970 SymmetricTensor<2, dim, Number> T_prime;
971 for (unsigned int i = 0; i < dim; ++i)
972 for (unsigned int j = i; j < dim; ++j)
973 T_prime[i][j] = T_prime_ns[i][j];
974
975 eig_vals_vecs = internal::SymmetricTensorImplementation::
976 perform_eigenvector_decomposition(T_prime, method);
977 }
978 else
979 {
980 Assert(dim == 3, ExcDimensionMismatch(dim, 3));
981
982 SymmetricTensor<2, dim, Number> T_prime;
983 Tensor<2, dim, Number> T_prime_ns;
984 for (unsigned int i = 0; i < dim; ++i)
985 {
986 // This is a little bit hacky, so here's a brief explanation
987 // as to what the principal of this operation is: What we're
988 // trying to do here is perturb our tensor such that the
989 // sensitivity of the eigenvectors with respect to each other
990 // can be established. So, one at a time, we compute the
991 // perturbation of the input tensor such that the maximal
992 // number of off-diagonal entries are non-zero for any given
993 // "i". This means that we rotation not about the "ith" axis,
994 // but rather some offset of it. Note: This does NOT lead to
995 // an exact value or derivative of the eigendata being
996 // computed, so one should be aware that for this case (where
997 // the eigenvalues are equal), the linearization of any
998 // resulting quantities is only approximate.
999 const unsigned int axis = (i + 2) % 3;
1000 T_prime_ns = internal::SymmetricTensorImplementation::
1001 dediagonalize_tensor(T, rotation_angle, axis);
1002
1003 // We can't symmetrize the tensor, otherwise the sensitivities
1004 // cancel out. So we take the upper triangle as an
1005 // approximation instead.
1006 // TODO[JPP]: Keep the full row and perform the
1007 // eigen-decomposition on the
1008 // non-symmetric T_prime_ns. See the related
1009 // comment above in the 2d case.
1010 for (unsigned int j = i; j < dim; ++j)
1011 T_prime[i][j] = T_prime_ns[i][j];
1012 }
1013 eig_vals_vecs = internal::SymmetricTensorImplementation::
1014 perform_eigenvector_decomposition(T_prime, method);
1015 }
1016 }
1017 }
1018 else
1019 eig_vals_vecs = internal::SymmetricTensorImplementation::
1020 perform_eigenvector_decomposition(T, method);
1021
1022 // Sort in descending order before output.
1023 std::sort(
1024 eig_vals_vecs.begin(),
1025 eig_vals_vecs.end(),
1026 internal::SymmetricTensorImplementation::SortEigenValuesVectors<dim,
1027 Number>());
1028 return eig_vals_vecs;
1029 }
1030
1031
1032
1033 #ifdef DEAL_II_ADOLC_WITH_ADVANCED_BRANCHING
1034 namespace internal
1035 {
1036 namespace SymmetricTensorImplementation
1037 {
1038 template <>
1039 struct Inverse<4, 3, adouble>;
1040 } // namespace SymmetricTensorImplementation
1041 } // namespace internal
1042
1043 template <>
1044 std::array<adouble, 1>
1045 eigenvalues(const SymmetricTensor<2, 1, adouble> & /*T*/);
1046
1047 template <>
1048 std::array<adouble, 2>
1049 eigenvalues(const SymmetricTensor<2, 2, adouble> & /*T*/);
1050
1051 template <>
1052 std::array<adouble, 3>
1053 eigenvalues(const SymmetricTensor<2, 3, adouble> & /*T*/);
1054
1055 template <>
1056 std::array<std::pair<adouble, Tensor<1, 1, adouble>>, 1>
1057 eigenvectors<1, adouble>(const SymmetricTensor<2, 1, adouble> & /*T*/,
1058 const SymmetricTensorEigenvectorMethod /*method*/);
1059
1060 template <>
1061 std::array<std::pair<adouble, Tensor<1, 2, adouble>>, 2>
1062 eigenvectors<2, adouble>(const SymmetricTensor<2, 2, adouble> & /*T*/,
1063 const SymmetricTensorEigenvectorMethod /*method*/);
1064
1065 template <>
1066 std::array<std::pair<adouble, Tensor<1, 3, adouble>>, 3>
1067 eigenvectors<3, adouble>(const SymmetricTensor<2, 3, adouble> & /*T*/,
1068 const SymmetricTensorEigenvectorMethod /*method*/);
1069 #endif
1070
1071 DEAL_II_NAMESPACE_CLOSE
1072
1073 #endif