Debian Codegraph @

include/deal.II/physics/transformations.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2016 - 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_transformations_h
16 #define dealii_transformations_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/symmetric_tensor.h>
21 #include <deal.II/base/tensor.h>
22
23 DEAL_II_NAMESPACE_OPEN
24
25
26 namespace Physics
27 {
28 namespace Transformations
29 {
30 /**
31 * Transformation functions and tensors that are defined in terms of
32 * rotation angles and axes of rotation.
33 */
34 namespace Rotations
35 {
36 /**
37 * @name Rotation matrices
38 */
39 /** @{ */
40
41 /**
42 * Return the rotation matrix for 2-d Euclidean space, namely
43 * @f[
44 * \mathbf{R} \dealcoloneq \left[ \begin{array}{cc}
45 * cos(\theta) & -sin(\theta) \\
46 * sin(\theta) & cos(\theta)
47 * \end{array}\right]
48 * @f]
49 * where $\theta$ is the rotation angle given in radians. In particular,
50 * this describes the counter-clockwise rotation of a vector relative to
51 * a <a href="http://mathworld.wolfram.com/RotationMatrix.html">fixed
52 * set of right-handed axes</a>.
53 *
54 * @param[in] angle The rotation angle (about the z-axis) in radians
55 */
56 template <typename Number>
57 Tensor<2, 2, Number>
58 rotation_matrix_2d(const Number &angle);
59
60
61 /**
62 * Return the rotation matrix for 3-d Euclidean space. Most concisely
63 * stated using the Rodrigues' rotation formula, this function returns
64 * the equivalent of
65 * @f[
66 * \mathbf{R} \dealcoloneq cos(\theta)\mathbf{I} + sin(\theta)\mathbf{W}
67 * + (1-cos(\theta))\mathbf{u}\otimes\mathbf{u}
68 * @f]
69 * where $\mathbf{u}$ is the axial vector (an axial vector) and $\theta$
70 * is the rotation angle given in radians, $\mathbf{I}$ is the identity
71 * tensor and $\mathbf{W}$ is the skew symmetric tensor of $\mathbf{u}$.
72 *
73 * @dealiiWriggersA{374,9.194} This presents Rodrigues' rotation
74 * formula, but the implementation used in this function is described in
75 * this <a
76 * href="https://en.wikipedia.org/wiki/Rotation_matrix#Rotation_matrix_from_axis_and_angle">wikipedia
77 * link</a>. In particular, this describes the counter-clockwise
78 * rotation of a vector <a
79 * href="http://mathworld.wolfram.com/RotationMatrix.html">in a plane
80 * with its normal</a>. defined by the @p axis of rotation. An
81 * alternative implementation is discussed at <a
82 * href="https://www.gamedev.net/resources/_/technical/math-and-physics/do-we-really-need-quaternions-r1199">this
83 * link</a>, but is inconsistent (sign-wise) with the Rodrigues'
84 * rotation formula as it describes the rotation of a coordinate system.
85 *
86 * @param[in] axis A unit vector that defines the axis of rotation
87 * @param[in] angle The rotation angle in radians
88 */
89 template <typename Number>
90 Tensor<2, 3, Number>
91 rotation_matrix_3d(const Tensor<1, 3, Number> &axis, const Number &angle);
92
93 /** @} */
94
95 } // namespace Rotations
96
97 /**
98 * Transformation of tensors that are defined in terms of a set of
99 * contravariant bases. Rank-1 and rank-2 contravariant tensors
100 * $\left(\bullet\right)^{\sharp} = \mathbf{T}$ (and its spatial
101 * counterpart $\mathbf{t}$) typically satisfy the relation
102 * @f[
103 * \int_{V_{0}} \nabla_{0} \cdot \mathbf{T} \; dV
104 * = \int_{\partial V_{0}} \mathbf{T} \cdot \mathbf{N} \; dA
105 * = \int_{\partial V_{t}} \mathbf{T} \cdot \mathbf{n} \; da
106 * = \int_{V_{t}} \nabla \cdot \mathbf{t} \; dv
107 * @f]
108 * where $V_{0}$ and $V_{t}$ are respectively control volumes in the
109 * reference and spatial configurations, and their surfaces $\partial
110 * V_{0}$ and $\partial V_{t}$ have the outwards facing normals
111 * $\mathbf{N}$ and $\mathbf{n}$.
112 */
113 namespace Contravariant
114 {
115 /**
116 * @name Push forward operations
117 */
118 /** @{ */
119
120 /**
121 * Return the result of the push forward transformation on a
122 * contravariant vector, i.e.
123 * @f[
124 * \chi\left(\bullet\right)^{\sharp}
125 * \dealcoloneq \mathbf{F} \cdot \left(\bullet\right)^{\sharp}
126 * @f]
127 *
128 * @param[in] V The (referential) vector to be operated on
129 * @param[in] F The deformation gradient tensor $\mathbf{F} \left(
130 * \mathbf{X} \right)$
131 * @return $\chi\left( \mathbf{V} \right)$
132 */
133 template <int dim, typename Number>
134 Tensor<1, dim, Number>
135 push_forward(const Tensor<1, dim, Number> &V,
136 const Tensor<2, dim, Number> &F);
137
138 /**
139 * Return the result of the push forward transformation on a rank-2
140 * contravariant tensor, i.e.
141 * @f[
142 * \chi\left(\bullet\right)^{\sharp}
143 * \dealcoloneq \mathbf{F} \cdot \left(\bullet\right)^{\sharp} \cdot
144 * \mathbf{F}^{T}
145 * @f]
146 *
147 * @param[in] T The (referential) rank-2 tensor to be operated on
148 * @param[in] F The deformation gradient tensor $\mathbf{F} \left(
149 * \mathbf{X} \right)$
150 * @return $\chi\left( \mathbf{T} \right)$
151 */
152 template <int dim, typename Number>
153 Tensor<2, dim, Number>
154 push_forward(const Tensor<2, dim, Number> &T,
155 const Tensor<2, dim, Number> &F);
156
157 /**
158 * Return the result of the push forward transformation on a rank-2
159 * contravariant symmetric tensor, i.e.
160 * @f[
161 * \chi\left(\bullet\right)^{\sharp}
162 * \dealcoloneq \mathbf{F} \cdot \left(\bullet\right)^{\sharp} \cdot
163 * \mathbf{F}^{T}
164 * @f]
165 *
166 * @param[in] T The (referential) rank-2 symmetric tensor to be operated
167 * on
168 * @param[in] F The deformation gradient tensor $\mathbf{F} \left(
169 * \mathbf{X} \right)$
170 * @return $\chi\left( \mathbf{T} \right)$
171 */
172 template <int dim, typename Number>
173 SymmetricTensor<2, dim, Number>
174 push_forward(const SymmetricTensor<2, dim, Number> &T,
175 const Tensor<2, dim, Number> &F);
176
177 /**
178 * Return the result of the push forward transformation on a rank-4
179 * contravariant tensor, i.e. (in index notation):
180 * @f[
181 * \left[ \chi\left(\bullet\right)^{\sharp} \right]_{ijkl}
182 * \dealcoloneq F_{iI} F_{jJ}
183 * \left(\bullet\right)^{\sharp}_{IJKL} F_{kK} F_{lL}
184 * @f]
185 *
186 * @param[in] H The (referential) rank-4 tensor to be operated on
187 * @param[in] F The deformation gradient tensor $\mathbf{F} \left(
188 * \mathbf{X} \right)$
189 * @return $\chi\left( \mathbf{H} \right)$
190 */
191 template <int dim, typename Number>
192 Tensor<4, dim, Number>
193 push_forward(const Tensor<4, dim, Number> &H,
194 const Tensor<2, dim, Number> &F);
195
196 /**
197 * Return the result of the push forward transformation on a rank-4
198 * contravariant symmetric tensor, i.e. (in index notation):
199 * @f[
200 * \left[ \chi\left(\bullet\right)^{\sharp} \right]_{ijkl}
201 * \dealcoloneq F_{iI} F_{jJ}
202 * \left(\bullet\right)^{\sharp}_{IJKL} F_{kK} F_{lL}
203 * @f]
204 *
205 * @param[in] H The (referential) rank-4 symmetric tensor to be operated
206 * on
207 * @param[in] F The deformation gradient tensor $\mathbf{F} \left(
208 * \mathbf{X} \right)$
209 * @return $\chi\left( \mathbf{H} \right)$
210 */
211 template <int dim, typename Number>
212 SymmetricTensor<4, dim, Number>
213 push_forward(const SymmetricTensor<4, dim, Number> &H,
214 const Tensor<2, dim, Number> &F);
215
216 /** @} */
217
218 /**
219 * @name Pull back operations
220 */
221 /** @{ */
222
223 /**
224 * Return the result of the pull back transformation on a contravariant
225 * vector, i.e.
226 * @f[
227 * \chi^{-1}\left(\bullet\right)^{\sharp}
228 * \dealcoloneq \mathbf{F}^{-1} \cdot \left(\bullet\right)^{\sharp}
229 * @f]
230 *
231 * @param[in] v The (spatial) vector to be operated on
232 * @param[in] F The deformation gradient tensor $\mathbf{F} \left(
233 * \mathbf{X} \right)$
234 * @return $\chi^{-1}\left( \mathbf{v} \right)$
235 */
236 template <int dim, typename Number>
237 Tensor<1, dim, Number>
238 pull_back(const Tensor<1, dim, Number> &v,
239 const Tensor<2, dim, Number> &F);
240
241 /**
242 * Return the result of the pull back transformation on a rank-2
243 * contravariant tensor, i.e.
244 * @f[
245 * \chi^{-1}\left(\bullet\right)^{\sharp}
246 * \dealcoloneq \mathbf{F}^{-1} \cdot \left(\bullet\right)^{\sharp}
247 * \cdot \mathbf{F}^{-T}
248 * @f]
249 *
250 * @param[in] t The (spatial) tensor to be operated on
251 * @param[in] F The deformation gradient tensor $\mathbf{F} \left(
252 * \mathbf{X} \right)$
253 * @return $\chi^{-1}\left( \mathbf{t} \right)$
254 */
255 template <int dim, typename Number>
256 Tensor<2, dim, Number>
257 pull_back(const Tensor<2, dim, Number> &t,
258 const Tensor<2, dim, Number> &F);
259
260 /**
261 * Return the result of the pull back transformation on a rank-2
262 * contravariant symmetric tensor, i.e.
263 * @f[
264 * \chi^{-1}\left(\bullet\right)^{\sharp}
265 * \dealcoloneq \mathbf{F}^{-1} \cdot \left(\bullet\right)^{\sharp}
266 * \cdot \mathbf{F}^{-T}
267 * @f]
268 *
269 * @param[in] t The (spatial) symmetric tensor to be operated on
270 * @param[in] F The deformation gradient tensor $\mathbf{F} \left(
271 * \mathbf{X} \right)$
272 * @return $\chi^{-1}\left( \mathbf{t} \right)$
273 */
274 template <int dim, typename Number>
275 SymmetricTensor<2, dim, Number>
276 pull_back(const SymmetricTensor<2, dim, Number> &t,
277 const Tensor<2, dim, Number> &F);
278
279 /**
280 * Return the result of the pull back transformation on a rank-4
281 * contravariant tensor, i.e. (in index notation):
282 * @f[
283 * \left[ \chi^{-1}\left(\bullet\right)^{\sharp} \right]_{IJKL}
284 * \dealcoloneq F^{-1}_{Ii} F^{-1}_{Jj}
285 * \left(\bullet\right)^{\sharp}_{ijkl} F^{-1}_{Kk} F^{-1}_{Ll}
286 * @f]
287 *
288 * @param[in] h The (spatial) tensor to be operated on
289 * @param[in] F The deformation gradient tensor $\mathbf{F} \left(
290 * \mathbf{X} \right)$
291 * @return $\chi^{-1}\left( \mathbf{h} \right)$
292 */
293 template <int dim, typename Number>
294 Tensor<4, dim, Number>
295 pull_back(const Tensor<4, dim, Number> &h,
296 const Tensor<2, dim, Number> &F);
297
298 /**
299 * Return the result of the pull back transformation on a rank-4
300 * contravariant symmetric tensor, i.e. (in index notation):
301 * @f[
302 * \left[ \chi^{-1}\left(\bullet\right)^{\sharp} \right]_{IJKL}
303 * \dealcoloneq F^{-1}_{Ii} F^{-1}_{Jj}
304 * \left(\bullet\right)^{\sharp}_{ijkl} F^{-1}_{Kk} F^{-1}_{Ll}
305 * @f]
306 *
307 * @param[in] h The (spatial) symmetric tensor to be operated on
308 * @param[in] F The deformation gradient tensor $\mathbf{F} \left(
309 * \mathbf{X} \right)$
310 * @return $\chi^{-1}\left( \mathbf{h} \right)$
311 */
312 template <int dim, typename Number>
313 SymmetricTensor<4, dim, Number>
314 pull_back(const SymmetricTensor<4, dim, Number> &h,
315 const Tensor<2, dim, Number> &F);
316
317 /** @} */
318 } // namespace Contravariant
319
320 /**
321 * Transformation of tensors that are defined in terms of a set of
322 * covariant basis vectors. Rank-1 and rank-2 covariant tensors
323 * $\left(\bullet\right)^{\flat} = \mathbf{T}$ (and its spatial
324 * counterpart $\mathbf{t}$) typically satisfy the relation
325 * @f[
326 * \int_{\partial V_{0}} \left[ \nabla_{0} \times \mathbf{T} \right]
327 * \cdot \mathbf{N} \; dA = \oint_{\partial A_{0}} \mathbf{T} \cdot
328 * \mathbf{L} \; dL = \oint_{\partial A_{t}} \mathbf{t} \cdot \mathbf{l} \;
329 * dl = \int_{\partial V_{t}} \left[ \nabla \times \mathbf{t} \right] \cdot
330 * \mathbf{n} \; da
331 * @f]
332 * where the control surfaces $\partial V_{0}$ and $\partial V_{t}$ with
333 * outwards facing normals $\mathbf{N}$ and $\mathbf{n}$ are bounded by
334 * the curves $\partial A_{0}$ and $\partial A_{t}$ that are,
335 * respectively, associated with the line directors $\mathbf{L}$ and
336 * $\mathbf{l}$.
337 */
338 namespace Covariant
339 {
340 /**
341 * @name Push forward operations
342 */
343 /** @{ */
344
345 /**
346 * Return the result of the push forward transformation on a covariant
347 * vector, i.e.
348 * @f[
349 * \chi\left(\bullet\right)^{\flat}
350 * \dealcoloneq \mathbf{F}^{-T} \cdot \left(\bullet\right)^{\flat}
351 * @f]
352 *
353 * @param[in] V The (referential) vector to be operated on
354 * @param[in] F The deformation gradient tensor $\mathbf{F} \left(
355 * \mathbf{X} \right)$
356 * @return $\chi\left( \mathbf{V} \right)$
357 */
358 template <int dim, typename Number>
359 Tensor<1, dim, Number>
360 push_forward(const Tensor<1, dim, Number> &V,
361 const Tensor<2, dim, Number> &F);
362
363 /**
364 * Return the result of the push forward transformation on a rank-2
365 * covariant tensor, i.e.
366 * @f[
367 * \chi\left(\bullet\right)^{\flat}
368 * \dealcoloneq \mathbf{F}^{-T} \cdot \left(\bullet\right)^{\flat}
369 * \cdot \mathbf{F}^{-1}
370 * @f]
371 *
372 * @param[in] T The (referential) rank-2 tensor to be operated on
373 * @param[in] F The deformation gradient tensor $\mathbf{F} \left(
374 * \mathbf{X} \right)$
375 * @return $\chi\left( \mathbf{T} \right)$
376 */
377 template <int dim, typename Number>
378 Tensor<2, dim, Number>
379 push_forward(const Tensor<2, dim, Number> &T,
380 const Tensor<2, dim, Number> &F);
381
382 /**
383 * Return the result of the push forward transformation on a rank-2
384 * covariant symmetric tensor, i.e.
385 * @f[
386 * \chi\left(\bullet\right)^{\flat}
387 * \dealcoloneq \mathbf{F}^{-T} \cdot \left(\bullet\right)^{\flat}
388 * \cdot \mathbf{F}^{-1}
389 * @f]
390 *
391 * @param[in] T The (referential) rank-2 symmetric tensor to be operated
392 * on
393 * @param[in] F The deformation gradient tensor $\mathbf{F} \left(
394 * \mathbf{X} \right)$
395 * @return $\chi\left( \mathbf{T} \right)$
396 */
397 template <int dim, typename Number>
398 SymmetricTensor<2, dim, Number>
399 push_forward(const SymmetricTensor<2, dim, Number> &T,
400 const Tensor<2, dim, Number> &F);
401
402 /**
403 * Return the result of the push forward transformation on a rank-4
404 * covariant tensor, i.e. (in index notation):
405 * @f[
406 * \left[ \chi\left(\bullet\right)^{\flat} \right]_{ijkl}
407 * \dealcoloneq F^{-T}_{iI} F^{-T}_{jJ}
408 * \left(\bullet\right)^{\flat}_{IJKL} F^{-T}_{kK} F^{-T}_{lL}
409 * @f]
410 *
411 * @param[in] H The (referential) rank-4 tensor to be operated on
412 * @param[in] F The deformation gradient tensor $\mathbf{F} \left(
413 * \mathbf{X} \right)$
414 * @return $\chi\left( \mathbf{H} \right)$
415 */
416 template <int dim, typename Number>
417 Tensor<4, dim, Number>
418 push_forward(const Tensor<4, dim, Number> &H,
419 const Tensor<2, dim, Number> &F);
420
421 /**
422 * Return the result of the push forward transformation on a rank-4
423 * covariant symmetric tensor, i.e. (in index notation):
424 * @f[
425 * \left[ \chi\left(\bullet\right)^{\flat} \right]_{ijkl}
426 * \dealcoloneq F^{-T}_{iI} F^{-T}_{jJ}
427 * \left(\bullet\right)^{\flat}_{IJKL} F^{-T}_{kK} F^{-T}_{lL}
428 * @f]
429 *
430 * @param[in] H The (referential) rank-4 symmetric tensor to be operated
431 * on
432 * @param[in] F The deformation gradient tensor $\mathbf{F} \left(
433 * \mathbf{X} \right)$
434 * @return $\chi\left( \mathbf{H} \right)$
435 */
436 template <int dim, typename Number>
437 SymmetricTensor<4, dim, Number>
438 push_forward(const SymmetricTensor<4, dim, Number> &H,
439 const Tensor<2, dim, Number> &F);
440
441 /** @} */
442
443 /**
444 * @name Pull back operations
445 */
446 /** @{ */
447
448 /**
449 * Return the result of the pull back transformation on a covariant
450 * vector, i.e.
451 * @f[
452 * \chi^{-1}\left(\bullet\right)^{\flat}
453 * \dealcoloneq \mathbf{F}^{T} \cdot \left(\bullet\right)^{\flat}
454 * @f]
455 *
456 * @param[in] v The (spatial) vector to be operated on
457 * @param[in] F The deformation gradient tensor $\mathbf{F} \left(
458 * \mathbf{X} \right)$
459 * @return $\chi^{-1}\left( \mathbf{v} \right)$
460 */
461 template <int dim, typename Number>
462 Tensor<1, dim, Number>
463 pull_back(const Tensor<1, dim, Number> &v,
464 const Tensor<2, dim, Number> &F);
465
466 /**
467 * Return the result of the pull back transformation on a rank-2
468 * covariant tensor, i.e.
469 * @f[
470 * \chi^{-1}\left(\bullet\right)^{\flat}
471 * \dealcoloneq \mathbf{F}^{T} \cdot \left(\bullet\right)^{\flat} \cdot
472 * \mathbf{F}
473 * @f]
474 *
475 * @param[in] t The (spatial) tensor to be operated on
476 * @param[in] F The deformation gradient tensor $\mathbf{F} \left(
477 * \mathbf{X} \right)$
478 * @return $\chi^{-1}\left( \mathbf{t} \right)$
479 */
480 template <int dim, typename Number>
481 Tensor<2, dim, Number>
482 pull_back(const Tensor<2, dim, Number> &t,
483 const Tensor<2, dim, Number> &F);
484
485 /**
486 * Return the result of the pull back transformation on a rank-2
487 * covariant symmetric tensor, i.e.
488 * @f[
489 * \chi^{-1}\left(\bullet\right)^{\flat}
490 * \dealcoloneq \mathbf{F}^{T} \cdot \left(\bullet\right)^{\flat}
491 * \cdot \mathbf{F}
492 * @f]
493 *
494 * @param[in] t The (spatial) symmetric tensor to be operated on
495 * @param[in] F The deformation gradient tensor $\mathbf{F} \left(
496 * \mathbf{X} \right)$
497 * @return $\chi^{-1}\left( \mathbf{t} \right)$
498 */
499 template <int dim, typename Number>
500 SymmetricTensor<2, dim, Number>
501 pull_back(const SymmetricTensor<2, dim, Number> &t,
502 const Tensor<2, dim, Number> &F);
503
504 /**
505 * Return the result of the pull back transformation on a rank-4
506 * contravariant tensor, i.e. (in index notation):
507 * @f[
508 * \left[ \chi^{-1}\left(\bullet\right)^{\flat} \right]_{IJKL}
509 * \dealcoloneq F^{T}_{Ii} F^{T}_{Jj}
510 * \left(\bullet\right)^{\flat}_{ijkl} F^{T}_{Kk} F^{T}_{Ll}
511 * @f]
512 *
513 * @param[in] h The (spatial) tensor to be operated on
514 * @param[in] F The deformation gradient tensor $\mathbf{F} \left(
515 * \mathbf{X} \right)$
516 * @return $\chi^{-1}\left( \mathbf{h} \right)$
517 */
518 template <int dim, typename Number>
519 Tensor<4, dim, Number>
520 pull_back(const Tensor<4, dim, Number> &h,
521 const Tensor<2, dim, Number> &F);
522
523 /**
524 * Return the result of the pull back transformation on a rank-4
525 * contravariant symmetric tensor, i.e. (in index notation):
526 * @f[
527 * \left[ \chi^{-1}\left(\bullet\right)^{\flat} \right]_{IJKL}
528 * \dealcoloneq F^{T}_{Ii} F^{T}_{Jj}
529 * \left(\bullet\right)^{\flat}_{ijkl} F^{T}_{Kk} F^{T}_{Ll}
530 * @f]
531 *
532 * @param[in] h The (spatial) symmetric tensor to be operated on
533 * @param[in] F The deformation gradient tensor $\mathbf{F} \left(
534 * \mathbf{X} \right)$
535 * @return $\chi^{-1}\left( \mathbf{h} \right)$
536 */
537 template <int dim, typename Number>
538 SymmetricTensor<4, dim, Number>
539 pull_back(const SymmetricTensor<4, dim, Number> &h,
540 const Tensor<2, dim, Number> &F);
541
542 /** @} */
543 } // namespace Covariant
544
545 /**
546 * Transformation of tensors that are defined in terms of a set of
547 * contravariant basis vectors and scale with the inverse of the volume
548 * change associated with the mapping.
549 */
550 namespace Piola
551 {
552 /**
553 * @name Push forward operations
554 */
555 /** @{ */
556
557 /**
558 * Return the result of the push forward transformation on a
559 * contravariant vector, i.e.
560 * @f[
561 * \textrm{det} \mathbf{F}^{-1} \; \chi\left(\bullet\right)^{\sharp}
562 * \dealcoloneq \frac{1}{\textrm{det} \mathbf{F}} \; \mathbf{F} \cdot
563 * \left(\bullet\right)^{\sharp}
564 * @f]
565 *
566 * @param[in] V The (referential) vector to be operated on
567 * @param[in] F The deformation gradient tensor $\mathbf{F} \left(
568 * \mathbf{X} \right)$
569 * @return $\frac{1}{\textrm{det} \mathbf{F}} \; \chi\left(
570 * \mathbf{V} \right)$
571 */
572 template <int dim, typename Number>
573 Tensor<1, dim, Number>
574 push_forward(const Tensor<1, dim, Number> &V,
575 const Tensor<2, dim, Number> &F);
576
577 /**
578 * Return the result of the push forward transformation on a rank-2
579 * contravariant tensor, i.e.
580 * @f[
581 * \textrm{det} \mathbf{F}^{-1} \; \chi\left(\bullet\right)^{\sharp}
582 * \dealcoloneq \frac{1}{\textrm{det} \mathbf{F}} \; \mathbf{F} \cdot
583 * \left(\bullet\right)^{\sharp} \cdot \mathbf{F}^{T}
584 * @f]
585 *
586 * @param[in] T The (referential) rank-2 tensor to be operated on
587 * @param[in] F The deformation gradient tensor $\mathbf{F} \left(
588 * \mathbf{X} \right)$
589 * @return $\frac{1}{\textrm{det} \mathbf{F}} \; \chi\left(
590 * \mathbf{T} \right)$
591 */
592 template <int dim, typename Number>
593 Tensor<2, dim, Number>
594 push_forward(const Tensor<2, dim, Number> &T,
595 const Tensor<2, dim, Number> &F);
596
597 /**
598 * Return the result of the push forward transformation on a rank-2
599 * contravariant symmetric tensor, i.e.
600 * @f[
601 * \textrm{det} \mathbf{F}^{-1} \; \chi\left(\bullet\right)^{\sharp}
602 * \dealcoloneq \frac{1}{\textrm{det} \mathbf{F}} \; \mathbf{F} \cdot
603 * \left(\bullet\right)^{\sharp} \cdot \mathbf{F}^{T}
604 * @f]
605 *
606 * @param[in] T The (referential) rank-2 symmetric tensor to be operated
607 * on
608 * @param[in] F The deformation gradient tensor $\mathbf{F} \left(
609 * \mathbf{X} \right)$
610 * @return $\frac{1}{\textrm{det} \mathbf{F}} \; \chi\left(
611 * \mathbf{T} \right)$
612 */
613 template <int dim, typename Number>
614 SymmetricTensor<2, dim, Number>
615 push_forward(const SymmetricTensor<2, dim, Number> &T,
616 const Tensor<2, dim, Number> &F);
617
618 /**
619 * Return the result of the push forward transformation on a rank-4
620 * contravariant tensor, i.e. (in index notation):
621 * @f[
622 * \textrm{det} \mathbf{F}^{-1} \; \left[
623 * \chi\left(\bullet\right)^{\sharp} \right]_{ijkl}
624 * \dealcoloneq \frac{1}{\textrm{det} \mathbf{F}} \; F_{iI} F_{jJ}
625 * \left(\bullet\right)^{\sharp}_{IJKL} F_{kK} F_{lL}
626 * @f]
627 *
628 * @param[in] H The (referential) rank-4 tensor to be operated on
629 * @param[in] F The deformation gradient tensor $\mathbf{F} \left(
630 * \mathbf{X} \right)$
631 * @return $\frac{1}{\textrm{det} \mathbf{F}} \; \chi\left(
632 * \mathbf{H} \right)$
633 */
634 template <int dim, typename Number>
635 Tensor<4, dim, Number>
636 push_forward(const Tensor<4, dim, Number> &H,
637 const Tensor<2, dim, Number> &F);
638
639 /**
640 * Return the result of the push forward transformation on a rank-4
641 * contravariant symmetric tensor, i.e. (in index notation):
642 * @f[
643 * \textrm{det} \mathbf{F}^{-1} \; \left[
644 * \chi\left(\bullet\right)^{\sharp} \right]_{ijkl}
645 * \dealcoloneq \frac{1}{\textrm{det} \mathbf{F}} \; F_{iI} F_{jJ}
646 * \left(\bullet\right)^{\sharp}_{IJKL} F_{kK} F_{lL}
647 * @f]
648 *
649 * @param[in] H The (referential) rank-4 symmetric tensor to be operated
650 * on
651 * @param[in] F The deformation gradient tensor $\mathbf{F} \left(
652 * \mathbf{X} \right)$
653 * @return $\frac{1}{\textrm{det} \mathbf{F}} \; \chi\left(
654 * \mathbf{H} \right)$
655 */
656 template <int dim, typename Number>
657 SymmetricTensor<4, dim, Number>
658 push_forward(const SymmetricTensor<4, dim, Number> &H,
659 const Tensor<2, dim, Number> &F);
660
661 /** @} */
662
663 /**
664 * @name Pull back operations
665 */
666 /** @{ */
667
668 /**
669 * Return the result of the pull back transformation on a contravariant
670 * vector, i.e.
671 * @f[
672 * \textrm{det} \mathbf{F} \; \chi^{-1}\left(\bullet\right)^{\sharp}
673 * \dealcoloneq \textrm{det} \mathbf{F} \; \mathbf{F}^{-1} \cdot
674 * \left(\bullet\right)^{\sharp}
675 * @f]
676 *
677 * @param[in] v The (spatial) vector to be operated on
678 * @param[in] F The deformation gradient tensor $\mathbf{F} \left(
679 * \mathbf{X} \right)$
680 * @return $\textrm{det} \mathbf{F} \; \chi^{-1}\left( \mathbf{v}
681 * \right)$
682 */
683 template <int dim, typename Number>
684 Tensor<1, dim, Number>
685 pull_back(const Tensor<1, dim, Number> &v,
686 const Tensor<2, dim, Number> &F);
687
688 /**
689 * Return the result of the pull back transformation on a rank-2
690 * contravariant tensor, i.e.
691 * @f[
692 * \textrm{det} \mathbf{F} \; \chi^{-1}\left(\bullet\right)^{\sharp}
693 * \dealcoloneq \textrm{det} \mathbf{F} \; \mathbf{F}^{-1} \cdot
694 * \left(\bullet\right)^{\sharp} \cdot \mathbf{F}^{-T}
695 * @f]
696 *
697 * @param[in] t The (spatial) tensor to be operated on
698 * @param[in] F The deformation gradient tensor $\mathbf{F} \left(
699 * \mathbf{X} \right)$
700 * @return $\textrm{det} \mathbf{F} \; \chi^{-1}\left( \mathbf{t}
701 * \right)$
702 */
703 template <int dim, typename Number>
704 Tensor<2, dim, Number>
705 pull_back(const Tensor<2, dim, Number> &t,
706 const Tensor<2, dim, Number> &F);
707
708 /**
709 * Return the result of the pull back transformation on a rank-2
710 * contravariant symmetric tensor, i.e.
711 * @f[
712 * \textrm{det} \mathbf{F} \; \chi^{-1}\left(\bullet\right)^{\sharp}
713 * \dealcoloneq \textrm{det} \mathbf{F} \; \mathbf{F}^{-1} \cdot
714 * \left(\bullet\right)^{\sharp} \cdot \mathbf{F}^{-T}
715 * @f]
716 *
717 * @param[in] t The (spatial) symmetric tensor to be operated on
718 * @param[in] F The deformation gradient tensor $\mathbf{F} \left(
719 * \mathbf{X} \right)$
720 * @return $\textrm{det} \mathbf{F} \; \chi^{-1}\left( \mathbf{t}
721 * \right)$
722 */
723 template <int dim, typename Number>
724 SymmetricTensor<2, dim, Number>
725 pull_back(const SymmetricTensor<2, dim, Number> &t,
726 const Tensor<2, dim, Number> &F);
727
728 /**
729 * Return the result of the pull back transformation on a rank-4
730 * contravariant tensor, i.e. (in index notation):
731 * @f[
732 * \textrm{det} \mathbf{F} \; \left[
733 * \chi^{-1}\left(\bullet\right)^{\sharp} \right]_{IJKL}
734 * \dealcoloneq \textrm{det} \mathbf{F} \; F^{-1}_{Ii} F^{-1}_{Jj}
735 * \left(\bullet\right)^{\sharp}_{ijkl} F^{-1}_{Kk} F^{-1}_{Ll}
736 * @f]
737 *
738 * @param[in] h The (spatial) tensor to be operated on
739 * @param[in] F The deformation gradient tensor $\mathbf{F} \left(
740 * \mathbf{X} \right)$
741 * @return $\textrm{det} \mathbf{F} \; \chi^{-1}\left( \mathbf{h}
742 * \right)$
743 */
744 template <int dim, typename Number>
745 Tensor<4, dim, Number>
746 pull_back(const Tensor<4, dim, Number> &h,
747 const Tensor<2, dim, Number> &F);
748
749 /**
750 * Return the result of the pull back transformation on a rank-4
751 * contravariant symmetric tensor, i.e. (in index notation):
752 * @f[
753 * \textrm{det} \mathbf{F} \; \left[
754 * \chi^{-1}\left(\bullet\right)^{\sharp} \right]_{IJKL}
755 * \dealcoloneq \textrm{det} \mathbf{F} \; F^{-1}_{Ii} F^{-1}_{Jj}
756 * \left(\bullet\right)^{\sharp}_{ijkl} F^{-1}_{Kk} F^{-1}_{Ll}
757 * @f]
758 *
759 * @param[in] h The (spatial) symmetric tensor to be operated on
760 * @param[in] F The deformation gradient tensor $\mathbf{F} \left(
761 * \mathbf{X} \right)$
762 * @return $\textrm{det} \mathbf{F} \; \chi^{-1}\left( \mathbf{h}
763 * \right)$
764 */
765 template <int dim, typename Number>
766 SymmetricTensor<4, dim, Number>
767 pull_back(const SymmetricTensor<4, dim, Number> &h,
768 const Tensor<2, dim, Number> &F);
769
770 /** @} */
771 } // namespace Piola
772
773 /**
774 * @name Special operations
775 */
776 /** @{ */
777
778 /**
779 * Return the result of applying Nanson's formula for the transformation
780 * of the material surface area element $d\mathbf{A}$ to the current
781 * surfaces area element $d\mathbf{a}$ under the nonlinear transformation
782 * map $\mathbf{x} = \boldsymbol{\varphi} \left( \mathbf{X} \right)$.
783 *
784 * The returned result is the spatial normal scaled by the ratio of areas
785 * between the reference and spatial surface elements, i.e.
786 * @f[
787 * \mathbf{n} \frac{da}{dA}
788 * \dealcoloneq \textrm{det} \mathbf{F} \, \mathbf{F}^{-T} \cdot \mathbf{N}
789 * = \textrm{cof} \mathbf{F} \cdot \mathbf{N} \, .
790 * @f]
791 *
792 * @param[in] N The referential normal unit vector $\mathbf{N}$
793 * @param[in] F The deformation gradient tensor $\mathbf{F} \left(
794 * \mathbf{X} \right)$
795 * @return The scaled spatial normal vector $\mathbf{n}
796 * \frac{da}{dA}$
797 *
798 * @dealiiHolzapfelA{75,2.55} @dealiiWriggersA{23,3.11}
799 */
800 template <int dim, typename Number>
801 Tensor<1, dim, Number>
802 nansons_formula(const Tensor<1, dim, Number> &N,
803 const Tensor<2, dim, Number> &F);
804
805 /** @} */
806
807 /**
808 * @name Basis transformations
809 */
810 /** @{ */
811
812 /**
813 * Return a vector with a changed basis, i.e.
814 * @f[
815 * \mathbf{V}^{\prime} \dealcoloneq \mathbf{B} \cdot \mathbf{V}
816 * @f]
817 *
818 * @param[in] V The vector to be transformed $\mathbf{V}$
819 * @param[in] B The transformation matrix $\mathbf{B}$
820 * @return $\mathbf{V}^{\prime}$
821 */
822 template <int dim, typename Number>
823 Tensor<1, dim, Number>
824 basis_transformation(const Tensor<1, dim, Number> &V,
825 const Tensor<2, dim, Number> &B);
826
827 /**
828 * Return a rank-2 tensor with a changed basis, i.e.
829 * @f[
830 * \mathbf{T}^{\prime} \dealcoloneq \mathbf{B} \cdot \mathbf{T} \cdot
831 * \mathbf{B}^{T}
832 * @f]
833 *
834 * @param[in] T The tensor to be transformed $\mathbf{T}$
835 * @param[in] B The transformation matrix $\mathbf{B}$
836 * @return $\mathbf{T}^{\prime}$
837 */
838 template <int dim, typename Number>
839 Tensor<2, dim, Number>
840 basis_transformation(const Tensor<2, dim, Number> &T,
841 const Tensor<2, dim, Number> &B);
842
843 /**
844 * Return a symmetric rank-2 tensor with a changed basis, i.e.
845 * @f[
846 * \mathbf{T}^{\prime} \dealcoloneq \mathbf{B} \cdot \mathbf{T} \cdot
847 * \mathbf{B}^{T}
848 * @f]
849 *
850 * @param[in] T The tensor to be transformed $\mathbf{T}$
851 * @param[in] B The transformation matrix $\mathbf{B}$
852 * @return $\mathbf{T}^{\prime}$
853 */
854 template <int dim, typename Number>
855 SymmetricTensor<2, dim, Number>
856 basis_transformation(const SymmetricTensor<2, dim, Number> &T,
857 const Tensor<2, dim, Number> &B);
858
859 /**
860 * Return a rank-4 tensor with a changed basis, i.e. (in index notation):
861 * @f[
862 * H_{ijkl}^{\prime} \dealcoloneq B_{iI} B_{jJ} H_{IJKL} B_{kK} B_{lL}
863 * @f]
864 *
865 * @param[in] H The tensor to be transformed $\mathbf{T}$
866 * @param[in] B The transformation matrix $\mathbf{B}$
867 * @return $\mathbf{H}^{\prime}$
868 */
869 template <int dim, typename Number>
870 Tensor<4, dim, Number>
871 basis_transformation(const Tensor<4, dim, Number> &H,
872 const Tensor<2, dim, Number> &B);
873
874 /**
875 * Return a symmetric rank-4 tensor with a changed basis, i.e. (in index
876 * notation):
877 * @f[
878 * H_{ijkl}^{\prime} \dealcoloneq B_{iI} B_{jJ} H_{IJKL} B_{kK} B_{lL}
879 * @f]
880 *
881 * @param[in] H The tensor to be transformed $\mathbf{T}$
882 * @param[in] B The transformation matrix $\mathbf{B}$
883 * @return $\mathbf{H}^{\prime}$
884 */
885 template <int dim, typename Number>
886 SymmetricTensor<4, dim, Number>
887 basis_transformation(const SymmetricTensor<4, dim, Number> &H,
888 const Tensor<2, dim, Number> &B);
889
890 /** @} */
891
892 } // namespace Transformations
893 } // namespace Physics
894
895
896
897 #ifndef DOXYGEN
898
899
900
901 template <typename Number>
902 Tensor<2, 2, Number>
903 Physics::Transformations::Rotations::rotation_matrix_2d(const Number &angle)
904 {
905 // Make things work with AD types
906 using std::cos;
907 using std::sin;
908
909 const Number rotation[2][2] = {{cos(angle), -sin(angle)},
910 {sin(angle), cos(angle)}};
911 return Tensor<2, 2>(rotation);
912 }
913
914
915
916 template <typename Number>
917 Tensor<2, 3, Number>
918 Physics::Transformations::Rotations::rotation_matrix_3d(
919 const Tensor<1, 3, Number> &axis,
920 const Number &angle)
921 {
922 // Make things work with AD types
923 using std::abs;
924 using std::cos;
925 using std::sin;
926
927 Assert(abs(axis.norm() - 1.0) < 1e-9,
928 ExcMessage("The supplied axial vector is not a unit vector."));
929 const Number c = cos(angle);
930 const Number s = sin(angle);
931 const Number t = 1. - c;
932 const Number rotation[3][3] = {{t * axis[0] * axis[0] + c,
933 t * axis[0] * axis[1] - s * axis[2],
934 t * axis[0] * axis[2] + s * axis[1]},
935 {t * axis[0] * axis[1] + s * axis[2],
936 t * axis[1] * axis[1] + c,
937 t * axis[1] * axis[2] - s * axis[0]},
938 {t * axis[0] * axis[2] - s * axis[1],
939 t * axis[1] * axis[2] + s * axis[0],
940 t * axis[2] * axis[2] + c}};
941 return Tensor<2, 3, Number>(rotation);
942 }
943
944
945
946 template <int dim, typename Number>
947 inline Tensor<1, dim, Number>
948 Physics::Transformations::Contravariant::push_forward(
949 const Tensor<1, dim, Number> &V,
950 const Tensor<2, dim, Number> &F)
951 {
952 return Physics::Transformations::basis_transformation(V, F);
953 }
954
955
956
957 template <int dim, typename Number>
958 inline Tensor<2, dim, Number>
959 Physics::Transformations::Contravariant::push_forward(
960 const Tensor<2, dim, Number> &T,
961 const Tensor<2, dim, Number> &F)
962 {
963 return Physics::Transformations::basis_transformation(T, F);
964 }
965
966
967
968 template <int dim, typename Number>
969 inline SymmetricTensor<2, dim, Number>
970 Physics::Transformations::Contravariant::push_forward(
971 const SymmetricTensor<2, dim, Number> &T,
972 const Tensor<2, dim, Number> &F)
973 {
974 return Physics::Transformations::basis_transformation(T, F);
975 }
976
977
978
979 template <int dim, typename Number>
980 inline Tensor<4, dim, Number>
981 Physics::Transformations::Contravariant::push_forward(
982 const Tensor<4, dim, Number> &H,
983 const Tensor<2, dim, Number> &F)
984 {
985 return Physics::Transformations::basis_transformation(H, F);
986 }
987
988
989
990 template <int dim, typename Number>
991 inline SymmetricTensor<4, dim, Number>
992 Physics::Transformations::Contravariant::push_forward(
993 const SymmetricTensor<4, dim, Number> &H,
994 const Tensor<2, dim, Number> &F)
995 {
996 return Physics::Transformations::basis_transformation(H, F);
997 }
998
999
1000
1001 template <int dim, typename Number>
1002 inline Tensor<1, dim, Number>
1003 Physics::Transformations::Contravariant::pull_back(
1004 const Tensor<1, dim, Number> &v,
1005 const Tensor<2, dim, Number> &F)
1006 {
1007 return Physics::Transformations::basis_transformation(v, invert(F));
1008 }
1009
1010
1011
1012 template <int dim, typename Number>
1013 inline Tensor<2, dim, Number>
1014 Physics::Transformations::Contravariant::pull_back(
1015 const Tensor<2, dim, Number> &t,
1016 const Tensor<2, dim, Number> &F)
1017 {
1018 return Physics::Transformations::basis_transformation(t, invert(F));
1019 }
1020
1021
1022
1023 template <int dim, typename Number>
1024 inline SymmetricTensor<2, dim, Number>
1025 Physics::Transformations::Contravariant::pull_back(
1026 const SymmetricTensor<2, dim, Number> &t,
1027 const Tensor<2, dim, Number> &F)
1028 {
1029 return Physics::Transformations::basis_transformation(t, invert(F));
1030 }
1031
1032
1033
1034 template <int dim, typename Number>
1035 inline Tensor<4, dim, Number>
1036 Physics::Transformations::Contravariant::pull_back(
1037 const Tensor<4, dim, Number> &h,
1038 const Tensor<2, dim, Number> &F)
1039 {
1040 return Physics::Transformations::basis_transformation(h, invert(F));
1041 }
1042
1043
1044
1045 template <int dim, typename Number>
1046 inline SymmetricTensor<4, dim, Number>
1047 Physics::Transformations::Contravariant::pull_back(
1048 const SymmetricTensor<4, dim, Number> &h,
1049 const Tensor<2, dim, Number> &F)
1050 {
1051 return Physics::Transformations::basis_transformation(h, invert(F));
1052 }
1053
1054
1055
1056 template <int dim, typename Number>
1057 inline Tensor<1, dim, Number>
1058 Physics::Transformations::Covariant::push_forward(
1059 const Tensor<1, dim, Number> &V,
1060 const Tensor<2, dim, Number> &F)
1061 {
1062 return Physics::Transformations::basis_transformation(V,
1063 transpose(invert(F)));
1064 }
1065
1066
1067
1068 template <int dim, typename Number>
1069 inline Tensor<2, dim, Number>
1070 Physics::Transformations::Covariant::push_forward(
1071 const Tensor<2, dim, Number> &T,
1072 const Tensor<2, dim, Number> &F)
1073 {
1074 return Physics::Transformations::basis_transformation(T,
1075 transpose(invert(F)));
1076 }
1077
1078
1079
1080 template <int dim, typename Number>
1081 inline SymmetricTensor<2, dim, Number>
1082 Physics::Transformations::Covariant::push_forward(
1083 const SymmetricTensor<2, dim, Number> &T,
1084 const Tensor<2, dim, Number> &F)
1085 {
1086 return Physics::Transformations::basis_transformation(T,
1087 transpose(invert(F)));
1088 }
1089
1090
1091
1092 template <int dim, typename Number>
1093 inline Tensor<4, dim, Number>
1094 Physics::Transformations::Covariant::push_forward(
1095 const Tensor<4, dim, Number> &H,
1096 const Tensor<2, dim, Number> &F)
1097 {
1098 return Physics::Transformations::basis_transformation(H,
1099 transpose(invert(F)));
1100 }
1101
1102
1103
1104 template <int dim, typename Number>
1105 inline SymmetricTensor<4, dim, Number>
1106 Physics::Transformations::Covariant::push_forward(
1107 const SymmetricTensor<4, dim, Number> &H,
1108 const Tensor<2, dim, Number> &F)
1109 {
1110 return Physics::Transformations::basis_transformation(H,
1111 transpose(invert(F)));
1112 }
1113
1114
1115
1116 template <int dim, typename Number>
1117 inline Tensor<1, dim, Number>
1118 Physics::Transformations::Covariant::pull_back(const Tensor<1, dim, Number> &v,
1119 const Tensor<2, dim, Number> &F)
1120 {
1121 return Physics::Transformations::basis_transformation(v, transpose(F));
1122 }
1123
1124
1125
1126 template <int dim, typename Number>
1127 inline Tensor<2, dim, Number>
1128 Physics::Transformations::Covariant::pull_back(const Tensor<2, dim, Number> &t,
1129 const Tensor<2, dim, Number> &F)
1130 {
1131 return Physics::Transformations::basis_transformation(t, transpose(F));
1132 }
1133
1134
1135
1136 template <int dim, typename Number>
1137 inline SymmetricTensor<2, dim, Number>
1138 Physics::Transformations::Covariant::pull_back(
1139 const SymmetricTensor<2, dim, Number> &t,
1140 const Tensor<2, dim, Number> &F)
1141 {
1142 return Physics::Transformations::basis_transformation(t, transpose(F));
1143 }
1144
1145
1146
1147 template <int dim, typename Number>
1148 inline Tensor<4, dim, Number>
1149 Physics::Transformations::Covariant::pull_back(const Tensor<4, dim, Number> &h,
1150 const Tensor<2, dim, Number> &F)
1151 {
1152 return Physics::Transformations::basis_transformation(h, transpose(F));
1153 }
1154
1155
1156
1157 template <int dim, typename Number>
1158 inline SymmetricTensor<4, dim, Number>
1159 Physics::Transformations::Covariant::pull_back(
1160 const SymmetricTensor<4, dim, Number> &h,
1161 const Tensor<2, dim, Number> &F)
1162 {
1163 return Physics::Transformations::basis_transformation(h, transpose(F));
1164 }
1165
1166
1167
1168 template <int dim, typename Number>
1169 inline Tensor<1, dim, Number>
1170 Physics::Transformations::Piola::push_forward(const Tensor<1, dim, Number> &V,
1171 const Tensor<2, dim, Number> &F)
1172 {
1173 return Number(1.0 / determinant(F)) * Contravariant::push_forward(V, F);
1174 }
1175
1176
1177
1178 template <int dim, typename Number>
1179 inline Tensor<2, dim, Number>
1180 Physics::Transformations::Piola::push_forward(const Tensor<2, dim, Number> &T,
1181 const Tensor<2, dim, Number> &F)
1182 {
1183 return Number(1.0 / determinant(F)) * Contravariant::push_forward(T, F);
1184 }
1185
1186
1187
1188 template <int dim, typename Number>
1189 inline SymmetricTensor<2, dim, Number>
1190 Physics::Transformations::Piola::push_forward(
1191 const SymmetricTensor<2, dim, Number> &T,
1192 const Tensor<2, dim, Number> &F)
1193 {
1194 return Number(1.0 / determinant(F)) * Contravariant::push_forward(T, F);
1195 }
1196
1197
1198
1199 template <int dim, typename Number>
1200 inline Tensor<4, dim, Number>
1201 Physics::Transformations::Piola::push_forward(const Tensor<4, dim, Number> &H,
1202 const Tensor<2, dim, Number> &F)
1203 {
1204 return Number(1.0 / determinant(F)) * Contravariant::push_forward(H, F);
1205 }
1206
1207
1208
1209 template <int dim, typename Number>
1210 inline SymmetricTensor<4, dim, Number>
1211 Physics::Transformations::Piola::push_forward(
1212 const SymmetricTensor<4, dim, Number> &H,
1213 const Tensor<2, dim, Number> &F)
1214 {
1215 return Number(1.0 / determinant(F)) * Contravariant::push_forward(H, F);
1216 }
1217
1218
1219
1220 template <int dim, typename Number>
1221 inline Tensor<1, dim, Number>
1222 Physics::Transformations::Piola::pull_back(const Tensor<1, dim, Number> &v,
1223 const Tensor<2, dim, Number> &F)
1224 {
1225 return Number(determinant(F)) * Contravariant::pull_back(v, F);
1226 }
1227
1228
1229
1230 template <int dim, typename Number>
1231 inline Tensor<2, dim, Number>
1232 Physics::Transformations::Piola::pull_back(const Tensor<2, dim, Number> &t,
1233 const Tensor<2, dim, Number> &F)
1234 {
1235 return Number(determinant(F)) * Contravariant::pull_back(t, F);
1236 }
1237
1238
1239
1240 template <int dim, typename Number>
1241 inline SymmetricTensor<2, dim, Number>
1242 Physics::Transformations::Piola::pull_back(
1243 const SymmetricTensor<2, dim, Number> &t,
1244 const Tensor<2, dim, Number> &F)
1245 {
1246 return Number(determinant(F)) * Contravariant::pull_back(t, F);
1247 }
1248
1249
1250
1251 template <int dim, typename Number>
1252 inline Tensor<4, dim, Number>
1253 Physics::Transformations::Piola::pull_back(const Tensor<4, dim, Number> &h,
1254 const Tensor<2, dim, Number> &F)
1255 {
1256 return Number(determinant(F)) * Contravariant::pull_back(h, F);
1257 }
1258
1259
1260
1261 template <int dim, typename Number>
1262 inline SymmetricTensor<4, dim, Number>
1263 Physics::Transformations::Piola::pull_back(
1264 const SymmetricTensor<4, dim, Number> &h,
1265 const Tensor<2, dim, Number> &F)
1266 {
1267 return Number(determinant(F)) * Contravariant::pull_back(h, F);
1268 }
1269
1270
1271
1272 template <int dim, typename Number>
1273 inline Tensor<1, dim, Number>
1274 Physics::Transformations::nansons_formula(const Tensor<1, dim, Number> &N,
1275 const Tensor<2, dim, Number> &F)
1276 {
1277 return cofactor(F) * N;
1278 }
1279
1280
1281 template <int dim, typename Number>
1282 inline Tensor<1, dim, Number>
1283 Physics::Transformations::basis_transformation(const Tensor<1, dim, Number> &V,
1284 const Tensor<2, dim, Number> &B)
1285 {
1286 return contract<1, 0>(B, V);
1287 }
1288
1289
1290
1291 template <int dim, typename Number>
1292 inline Tensor<2, dim, Number>
1293 Physics::Transformations::basis_transformation(const Tensor<2, dim, Number> &T,
1294 const Tensor<2, dim, Number> &B)
1295 {
1296 return contract<1, 0>(B, contract<1, 1>(T, B));
1297 }
1298
1299
1300
1301 template <int dim, typename Number>
1302 inline SymmetricTensor<2, dim, Number>
1303 Physics::Transformations::basis_transformation(
1304 const SymmetricTensor<2, dim, Number> &T,
1305 const Tensor<2, dim, Number> &B)
1306 {
1307 Tensor<2, dim, Number> tmp_1;
1308 for (unsigned int i = 0; i < dim; ++i)
1309 for (unsigned int J = 0; J < dim; ++J)
1310 // Loop over I but complex.h defines a macro I, so use I_ instead
1311 for (unsigned int I_ = 0; I_ < dim; ++I_)
1312 tmp_1[i][J] += B[i][I_] * T[I_][J];
1313
1314 SymmetricTensor<2, dim, Number> out;
1315 for (unsigned int i = 0; i < dim; ++i)
1316 for (unsigned int j = i; j < dim; ++j)
1317 for (unsigned int J = 0; J < dim; ++J)
1318 out[i][j] += B[j][J] * tmp_1[i][J];
1319
1320 return out;
1321 }
1322
1323
1324
1325 template <int dim, typename Number>
1326 inline Tensor<4, dim, Number>
1327 Physics::Transformations::basis_transformation(const Tensor<4, dim, Number> &H,
1328 const Tensor<2, dim, Number> &B)
1329 {
1330 // This contraction order and indexing might look a bit dubious, so a
1331 // quick explanation as to what's going on is probably in order:
1332 //
1333 // When the contract() function operates on the inner indices, the
1334 // result has the inner index and outer index transposed, i.e.
1335 // contract<2,1>(H,F) implies
1336 // T_{IJLk} = (H_{IJMN} F_{mM}) \delta_{mL} \delta_{Nk}
1337 // rather than T_{IJkL} (the desired result).
1338 // So, in effect, contraction of the 3rd (inner) index with F as the
1339 // second argument results in its transposition with respect to its
1340 // adjacent neighbor. This is due to the position of the argument F,
1341 // leading to the free index being on the right hand side of the result.
1342 // However, given that we can do two transformations from the LHS of H
1343 // and two from the right we can undo the otherwise erroneous
1344 // swapping of the outer indices upon application of the second
1345 // sets of contractions.
1346 //
1347 // Note: Its significantly quicker (in 3d) to push forward
1348 // each index individually
1349 return contract<1, 1>(
1350 B, contract<1, 1>(B, contract<2, 1>(contract<2, 1>(H, B), B)));
1351 }
1352
1353
1354
1355 template <int dim, typename Number>
1356 inline SymmetricTensor<4, dim, Number>
1357 Physics::Transformations::basis_transformation(
1358 const SymmetricTensor<4, dim, Number> &H,
1359 const Tensor<2, dim, Number> &B)
1360 {
1361 // The first and last transformation operations respectively
1362 // break and recover the symmetry properties of the tensors.
1363 // We also want to perform a minimal number of operations here
1364 // and avoid some complications related to the transposition of
1365 // tensor indices when contracting inner indices using the contract()
1366 // function. (For an explanation of the contraction operations,
1367 // please see the note in the equivalent function for standard
1368 // Tensors.) So what we'll do here is manually perform the first
1369 // and last contractions that break/recover the tensor symmetries
1370 // on the inner indices, and use the contract() function only on
1371 // the outer indices.
1372 //
1373 // Note: Its significantly quicker (in 3d) to push forward
1374 // each index individually
1375
1376 // Push forward (inner) index 1
1377 Tensor<4, dim, Number> tmp;
1378 // Loop over I but complex.h defines a macro I, so use I_ instead
1379 for (unsigned int I_ = 0; I_ < dim; ++I_)
1380 for (unsigned int j = 0; j < dim; ++j)
1381 for (unsigned int K = 0; K < dim; ++K)
1382 for (unsigned int L = 0; L < dim; ++L)
1383 for (unsigned int J = 0; J < dim; ++J)
1384 tmp[I_][j][K][L] += B[j][J] * H[I_][J][K][L];
1385
1386 // Push forward (outer) indices 0 and 3
1387 tmp = contract<1, 0>(B, contract<3, 1>(tmp, B));
1388
1389 // Push forward (inner) index 2
1390 SymmetricTensor<4, dim, Number> out;
1391 for (unsigned int i = 0; i < dim; ++i)
1392 for (unsigned int j = i; j < dim; ++j)
1393 for (unsigned int k = 0; k < dim; ++k)
1394 for (unsigned int l = k; l < dim; ++l)
1395 for (unsigned int K = 0; K < dim; ++K)
1396 out[i][j][k][l] += B[k][K] * tmp[i][j][K][l];
1397
1398 return out;
1399 }
1400
1401 #endif // DOXYGEN
1402
1403 DEAL_II_NAMESPACE_CLOSE
1404
1405 #endif