Reference documentation for deal.II version 9.6.1
 
\(\newcommand{\dealvcentcolon}{\mathrel{\mathop{:}}}\) \(\newcommand{\dealcoloneq}{\dealvcentcolon\mathrel{\mkern-1.2mu}=}\) \(\newcommand{\jump}[1]{\left[\!\left[ #1 \right]\!\right]}\) \(\newcommand{\average}[1]{\left\{\!\left\{ #1 \right\}\!\right\}}\)
Loading...
Searching...
No Matches
tensor.h File Reference
#include <deal.II/base/config.h>
#include <deal.II/base/exceptions.h>
#include <deal.II/base/kokkos.h>
#include <deal.II/base/numbers.h>
#include <deal.II/base/table_indices.h>
#include <deal.II/base/template_constraints.h>
#include <deal.II/base/tensor_accessors.h>
#include <adolc/adouble.h>
#include <boost/version.hpp>
#include <boost/serialization/array.hpp>
#include <array>
#include <cmath>
#include <ostream>
#include <type_traits>

Go to the source code of this file.

Classes

class  Tensor< 0, dim, Number >
 
class  Tensor< rank_, dim, Number >
 

Function Documentation

◆ operator<<() [1/2]

template<int rank_, int dim, typename Number>
std::ostream & operator<< ( std::ostream & out,
const Tensor< rank_, dim, Number > & p )
related

Output operator for tensors. Print the elements consecutively, with a space in between, two spaces between rank 1 subtensors, three between rank 2 and so on.

Definition at line 1949 of file tensor.h.

◆ operator<<() [2/2]

template<int dim, typename Number>
std::ostream & operator<< ( std::ostream & out,
const Tensor< 0, dim, Number > & p )
related

Output operator for tensors of rank 0. Since such tensors are scalars, we simply print this one value.

Definition at line 1971 of file tensor.h.

◆ operator*() [1/6]

template<int dim, typename Number, typename Other>
ProductType< Other, Number >::type operator* ( const Other & object,
const Tensor< 0, dim, Number > & t )
related

Scalar multiplication of a tensor of rank 0 with an object from the left.

This function unwraps the underlying Number stored in the Tensor and multiplies object with it.

Note
This function can also be used in device code.

Definition at line 2000 of file tensor.h.

◆ operator*() [2/6]

template<int dim, typename Number, typename Other>
ProductType< Number, Other >::type operator* ( const Tensor< 0, dim, Number > & t,
const Other & object )
related

Scalar multiplication of a tensor of rank 0 with an object from the right.

This function unwraps the underlying Number stored in the Tensor and multiplies object with it.

Note
This function can also be used in device code.

Definition at line 2020 of file tensor.h.

◆ operator*() [3/6]

template<int dim, typename Number, typename OtherNumber>
ProductType< Number, OtherNumber >::type operator* ( const Tensor< 0, dim, Number > & src1,
const Tensor< 0, dim, OtherNumber > & src2 )
related

Scalar multiplication of two tensors of rank 0.

This function unwraps the underlying objects of type Number and OtherNumber that are stored within the Tensor and multiplies them. It returns an unwrapped number of product type.

Note
This function can also be used in device code.

Definition at line 2040 of file tensor.h.

◆ operator/() [1/2]

template<int dim, typename Number, typename OtherNumber>
Tensor< 0, dim, typename ProductType< Number, typename EnableIfScalar< OtherNumber >::type >::type > operator/ ( const Tensor< 0, dim, Number > & t,
const OtherNumber & factor )
related

Division of a tensor of rank 0 by a scalar number.

Note
This function can also be used in device code.

Definition at line 2061 of file tensor.h.

◆ operator+() [1/2]

template<int dim, typename Number, typename OtherNumber>
DEAL_II_HOST_DEVICE_ALWAYS_INLINE Tensor< 0, dim, typename ProductType< Number, OtherNumber >::type > operator+ ( const Tensor< 0, dim, Number > & p,
const Tensor< 0, dim, OtherNumber > & q )
related

Add two tensors of rank 0.

Note
This function can also be used in device code.

Definition at line 2077 of file tensor.h.

◆ operator-() [1/2]

template<int dim, typename Number, typename OtherNumber>
DEAL_II_HOST_DEVICE_ALWAYS_INLINE Tensor< 0, dim, typename ProductType< Number, OtherNumber >::type > operator- ( const Tensor< 0, dim, Number > & p,
const Tensor< 0, dim, OtherNumber > & q )
related

Subtract two tensors of rank 0.

Note
This function can also be used in device code.

Definition at line 2094 of file tensor.h.

◆ operator*() [4/6]

template<int rank, int dim, typename Number, typename OtherNumber>
Tensor< rank, dim, typename ProductType< Number, typename EnableIfScalar< OtherNumber >::type >::type > operator* ( const Tensor< rank, dim, Number > & t,
const OtherNumber & factor )
related

Multiplication of a tensor of general rank with a scalar number from the right.

Only multiplication with a scalar number type (i.e., a floating point number, a complex floating point number, etc.) is allowed, see the documentation of EnableIfScalar for details.

Note
This function can also be used in device code.

Definition at line 2119 of file tensor.h.

◆ operator*() [5/6]

template<int rank, int dim, typename Number, typename OtherNumber>
Tensor< rank, dim, typename ProductType< typename EnableIfScalar< Number >::type, OtherNumber >::type > operator* ( const Number & factor,
const Tensor< rank, dim, OtherNumber > & t )
related

Multiplication of a tensor of general rank with a scalar number from the left.

Only multiplication with a scalar number type (i.e., a floating point number, a complex floating point number, etc.) is allowed, see the documentation of EnableIfScalar for details.

Note
This function can also be used in device code.

Definition at line 2145 of file tensor.h.

◆ operator/() [2/2]

template<int rank, int dim, typename Number, typename OtherNumber>
Tensor< rank, dim, typename ProductType< Number, typename EnableIfScalar< OtherNumber >::type >::type > operator/ ( const Tensor< rank, dim, Number > & t,
const OtherNumber & factor )
related

Division of a tensor of general rank with a scalar number. See the discussion on operator*() above for more information about template arguments and the return type.

Note
This function can also be used in device code.

Definition at line 2168 of file tensor.h.

◆ operator+() [2/2]

template<int rank, int dim, typename Number, typename OtherNumber>
Tensor< rank, dim, typename ProductType< Number, OtherNumber >::type > operator+ ( const Tensor< rank, dim, Number > & p,
const Tensor< rank, dim, OtherNumber > & q )
related

Addition of two tensors of general rank.

Template Parameters
rankThe rank of both tensors.
Note
This function can also be used in device code.

Definition at line 2188 of file tensor.h.

◆ operator-() [2/2]

template<int rank, int dim, typename Number, typename OtherNumber>
Tensor< rank, dim, typename ProductType< Number, OtherNumber >::type > operator- ( const Tensor< rank, dim, Number > & p,
const Tensor< rank, dim, OtherNumber > & q )
related

Subtraction of two tensors of general rank.

Template Parameters
rankThe rank of both tensors.
Note
This function can also be used in device code.

Definition at line 2209 of file tensor.h.

◆ schur_product() [1/2]

template<int dim, typename Number, typename OtherNumber>
Tensor< 0, dim, typename ProductType< Number, OtherNumber >::type > schur_product ( const Tensor< 0, dim, Number > & src1,
const Tensor< 0, dim, OtherNumber > & src2 )
related

Entrywise multiplication of two tensor objects of rank 0 (i.e. the multiplication of two scalar values).

Definition at line 2226 of file tensor.h.

◆ schur_product() [2/2]

template<int rank, int dim, typename Number, typename OtherNumber>
Tensor< rank, dim, typename ProductType< Number, OtherNumber >::type > schur_product ( const Tensor< rank, dim, Number > & src1,
const Tensor< rank, dim, OtherNumber > & src2 )
related

Entrywise multiplication of two tensor objects of general rank.

This multiplication is also called "Hadamard-product" (c.f. https://en.wikipedia.org/wiki/Hadamard_product_(matrices)), and generates a new tensor of size <rank, dim>:

\[  \text{result}_{i, j}
  = \text{left}_{i, j}\circ
    \text{right}_{i, j}
\]

Template Parameters
rankThe rank of both tensors.

Definition at line 2255 of file tensor.h.

◆ operator*() [6/6]

template<int rank_1, int rank_2, int dim, typename Number, typename OtherNumber>
Tensor< rank_1+rank_2-2, dim, typenameProductType< Number, OtherNumber >::type >::tensor_type operator* ( const Tensor< rank_1, dim, Number > & src1,
const Tensor< rank_2, dim, OtherNumber > & src2 )
related

The dot product (single contraction) for tensors. This function return a tensor of rank $(\text{rank}_1 + \text{rank}_2 - 2)$ that is the contraction of the last index of a tensor src1 of rank rank_1 with the first index of a tensor src2 of rank rank_2:

\[  \text{result}_{i_1,\ldots,i_{r1},j_1,\ldots,j_{r2}}
  = \sum_{k}
    \text{left}_{i_1,\ldots,i_{r1}, k}
    \text{right}_{k, j_1,\ldots,j_{r2}}
\]

Note
For the Tensor class, the multiplication operator only performs a contraction over a single pair of indices. This is in contrast to the multiplication operator for SymmetricTensor, for which the corresponding operator*() performs a double contraction. The origin of the difference in how operator*() is implemented between Tensor and SymmetricTensor is that for the former, the product between two Tensor objects of same rank and dimension results in another Tensor object – that it, operator*() corresponds to the multiplicative group action within the group of tensors. On the other hand, there is no corresponding multiplicative group action with the set of symmetric tensors because, in general, the product of two symmetric tensors is a nonsymmetric tensor. As a consequence, for a mathematician, it is clear that operator*() for symmetric tensors must have a different meaning: namely the dot or scalar product that maps two symmetric tensors of rank 2 to a scalar. This corresponds to the double-dot (colon) operator whose meaning is then extended to the product of any two even-ranked symmetric tensors.
In case the contraction yields a tensor of rank 0, that is, if rank_1==rank_2==1, then a scalar number is returned as an unwrapped number type.

Definition at line 2321 of file tensor.h.

◆ contract()

template<int index_1, int index_2, int rank_1, int rank_2, int dim, typename Number, typename OtherNumber>
Tensor< rank_1+rank_2-2, dim, typenameProductType< Number, OtherNumber >::type >::tensor_type contract ( const Tensor< rank_1, dim, Number > & src1,
const Tensor< rank_2, dim, OtherNumber > & src2 )
related

Generic contraction of a pair of indices of two tensors of arbitrary rank: Return a tensor of rank $(\text{rank}_1 + \text{rank}_2 - 2)$ that is the contraction of index index_1 of a tensor src1 of rank rank_1 with the index index_2 of a tensor src2 of rank rank_2:

\[  \text{result}_{i_1,\ldots,i_{r1},j_1,\ldots,j_{r2}}
  = \sum_{k}
    \text{left}_{i_1,\ldots,k,\ldots,i_{r1}}
    \text{right}_{j_1,\ldots,k,\ldots,j_{r2}}
\]

If for example the first index (index_1==0) of a tensor t1 shall be contracted with the third index (index_2==2) of a tensor t2, this function should be invoked as

constexpr Tensor< rank_1+rank_2-2, dim, typenameProductType< Number, OtherNumber >::type >::tensor_type contract(const Tensor< rank_1, dim, Number > &src1, const Tensor< rank_2, dim, OtherNumber > &src2)
Definition tensor.h:2415
Note
The position of the index is counted from 0, i.e., $0\le\text{index}_i<\text{range}_i$.
In case the contraction yields a tensor of rank 0 the scalar number is returned as an unwrapped number type.

Definition at line 2415 of file tensor.h.

◆ double_contract()

template<int index_1, int index_2, int index_3, int index_4, int rank_1, int rank_2, int dim, typename Number, typename OtherNumber>
Tensor< rank_1+rank_2-4, dim, typenameProductType< Number, OtherNumber >::type >::tensor_type double_contract ( const Tensor< rank_1, dim, Number > & src1,
const Tensor< rank_2, dim, OtherNumber > & src2 )
related

Generic contraction of two pairs of indices of two tensors of arbitrary rank: Return a tensor of rank $(\text{rank}_1 + \text{rank}_2 - 4)$ that is the contraction of index index_1 with index index_2, and index index_3 with index index_4 of a tensor src1 of rank rank_1 and a tensor src2 of rank rank_2:

\[  \text{result}_{i_1,\ldots,i_{r1},j_1,\ldots,j_{r2}}
  = \sum_{k, l}
    \text{left}_{i_1,\ldots,k,\ldots,l,\ldots,i_{r1}}
    \text{right}_{j_1,\ldots,k,\ldots,l\ldots,j_{r2}}
\]

If for example the first index (index_1==0) shall be contracted with the third index (index_2==2), and the second index (index_3==1) with the first index (index_4==0) of a tensor t2, this function should be invoked as

constexpr Tensor< rank_1+rank_2-4, dim, typenameProductType< Number, OtherNumber >::type >::tensor_type double_contract(const Tensor< rank_1, dim, Number > &src1, const Tensor< rank_2, dim, OtherNumber > &src2)
Definition tensor.h:2490
Note
The position of the index is counted from 0, i.e., $0\le\text{index}_i<\text{range}_i$.
In case the contraction yields a tensor of rank 0 the scalar number is returned as an unwrapped number type.

Definition at line 2490 of file tensor.h.

◆ scalar_product()

template<int rank, int dim, typename Number, typename OtherNumber>
ProductType< Number, OtherNumber >::type scalar_product ( const Tensor< rank, dim, Number > & left,
const Tensor< rank, dim, OtherNumber > & right )
related

The scalar product, or (generalized) Frobenius inner product of two tensors of equal rank: Return a scalar number that is the result of a full contraction of a tensor left and right:

\[  \sum_{i_1,\ldots,i_r}
  \text{left}_{i_1,\ldots,i_r}
  \text{right}_{i_1,\ldots,i_r}
\]

Definition at line 2569 of file tensor.h.

◆ contract3()

template<template< int, int, typename > class TensorT1, template< int, int, typename > class TensorT2, template< int, int, typename > class TensorT3, int rank_1, int rank_2, int dim, typename T1, typename T2, typename T3>
ProductType< T1, typenameProductType< T2, T3 >::type >::type contract3 ( const TensorT1< rank_1, dim, T1 > & left,
const TensorT2< rank_1+rank_2, dim, T2 > & middle,
const TensorT3< rank_2, dim, T3 > & right )
related

Full contraction of three tensors: Return a scalar number that is the result of a full contraction of a tensor left of rank rank_1, a tensor middle of rank $(\text{rank}_1+\text{rank}_2)$ and a tensor right of rank rank_2:

\[  \sum_{i_1,\ldots,i_{r1},j_1,\ldots,j_{r2}}
  \text{left}_{i_1,\ldots,i_{r1}}
  \text{middle}_{i_1,\ldots,i_{r1},j_1,\ldots,j_{r2}}
  \text{right}_{j_1,\ldots,j_{r2}}
\]

Note
Each of the three input tensors can be either a Tensor or SymmetricTensor.

Definition at line 2608 of file tensor.h.

◆ outer_product()

template<int rank_1, int rank_2, int dim, typename Number, typename OtherNumber>
Tensor< rank_1+rank_2, dim, typename ProductType< Number, OtherNumber >::type > outer_product ( const Tensor< rank_1, dim, Number > & src1,
const Tensor< rank_2, dim, OtherNumber > & src2 )
related

The outer product of two tensors of rank_1 and rank_2: Returns a tensor of rank $(\text{rank}_1 + \text{rank}_2)$:

\[  \text{result}_{i_1,\ldots,i_{r1},j_1,\ldots,j_{r2}}
  = \text{left}_{i_1,\ldots,i_{r1}}\,\text{right}_{j_1,\ldots,j_{r2}.}
\]

Definition at line 2637 of file tensor.h.

◆ cross_product_2d()

template<int dim, typename Number>
Tensor< 1, dim, Number > cross_product_2d ( const Tensor< 1, dim, Number > & src)
related

Return the cross product in 2d. This is just a rotation by 90 degrees clockwise to compute the outer normal from a tangential vector. This function is defined for all space dimensions to allow for dimension independent programming (e.g. within switches over the space dimension), but may only be called if the actual dimension of the arguments is two (e.g. from the dim==2 case in the switch).

Definition at line 2669 of file tensor.h.

◆ cross_product_3d()

template<int dim, typename Number1, typename Number2>
Tensor< 1, dim, typename ProductType< Number1, Number2 >::type > cross_product_3d ( const Tensor< 1, dim, Number1 > & src1,
const Tensor< 1, dim, Number2 > & src2 )
related

Return the cross product of 2 vectors in 3d. This function is defined for all space dimensions to allow for dimension independent programming (e.g. within switches over the space dimension), but may only be called if the actual dimension of the arguments is three (e.g. from the dim==3 case in the switch).

Definition at line 2694 of file tensor.h.

◆ determinant() [1/4]

template<int dim, typename Number>
Number determinant ( const Tensor< 2, dim, Number > & t)
related

Compute the determinant of a tensor or rank 2.

Definition at line 2729 of file tensor.h.

◆ determinant() [2/4]

template<typename Number>
Number determinant ( const Tensor< 2, 1, Number > & t)
related

Specialization for dim==1.

Definition at line 2757 of file tensor.h.

◆ determinant() [3/4]

template<typename Number>
Number determinant ( const Tensor< 2, 2, Number > & t)
related

Specialization for dim==2.

Definition at line 2769 of file tensor.h.

◆ determinant() [4/4]

template<typename Number>
Number determinant ( const Tensor< 2, 3, Number > & t)
related

Specialization for dim==3.

Definition at line 2782 of file tensor.h.

◆ trace()

template<int dim, typename Number>
Number trace ( const Tensor< 2, dim, Number > & d)
related

Compute and return the trace of a tensor of rank 2, i.e. the sum of its diagonal entries.

Definition at line 2803 of file tensor.h.

◆ invert()

template<int dim, typename Number>
Tensor< 2, dim, Number > invert ( const Tensor< 2, dim, Number > & )
related

Compute and return the inverse of the given tensor. Since the compiler can perform the return value optimization, and since the size of the return object is known, it is acceptable to return the result by value, rather than by reference as a parameter.

Definition at line 2822 of file tensor.h.

◆ transpose()

template<int dim, typename Number>
Tensor< 2, dim, Number > transpose ( const Tensor< 2, dim, Number > & t)
related

Return the transpose of the given tensor.

Definition at line 2904 of file tensor.h.

◆ adjugate()

template<int dim, typename Number>
Tensor< 2, dim, Number > adjugate ( const Tensor< 2, dim, Number > & t)
related

Return the adjugate of the given tensor of rank 2. The adjugate of a tensor $\mathbf A$ is defined as

\[ \textrm{adj}\mathbf A
  \dealcoloneq \textrm{det}\mathbf A \; \mathbf{A}^{-1}
\; .
\]

Note
This requires that the tensor is invertible.

Definition at line 2935 of file tensor.h.

◆ cofactor()

template<int dim, typename Number>
Tensor< 2, dim, Number > cofactor ( const Tensor< 2, dim, Number > & t)
related

Return the cofactor of the given tensor of rank 2. The cofactor of a tensor $\mathbf A$ is defined as

\[ \textrm{cof}\mathbf A
  \dealcoloneq \textrm{det}\mathbf A \; \mathbf{A}^{-T}
   = \left[ \textrm{adj}\mathbf A \right]^{T} \; .
\]

Note
This requires that the tensor is invertible.

Definition at line 2956 of file tensor.h.

◆ project_onto_orthogonal_tensors()

template<int dim, typename Number>
Tensor< 2, dim, Number > project_onto_orthogonal_tensors ( const Tensor< 2, dim, Number > & A)
related

Return the nearest orthogonal matrix $\hat {\mathbf A}=\mathbf U \mathbf{V}^T$ by combining the products of the singular value decomposition (SVD) ${\mathbf A}=\mathbf U  \mathbf S \mathbf V^T$ for a given input ${\mathbf A}$, effectively replacing $\mathbf S$ with the identity matrix.

This is a (nonlinear) projection operation since when applied twice, we have $\hat{\hat{\mathbf A}}=\hat{\mathbf A}$ as is easy to see. (That is because the SVD of $\hat {\mathbf A}$ is simply $\mathbf U \mathbf I \mathbf{V}^T$.) Furthermore, $\hat {\mathbf A}$ is really an orthogonal matrix because orthogonal matrices have to satisfy ${\hat {\mathbf A}}^T \hat {\mathbf A}={\mathbf I}$, which here implies that

\begin{align*}  {\hat {\mathbf A}}^T \hat {\mathbf A}
  &=
  \left(\mathbf U \mathbf{V}^T\right)^T\left(\mathbf U \mathbf{V}^T\right)
  \\
  &=
  \mathbf V \mathbf{U}^T
  \mathbf U \mathbf{V}^T
  \\
  &=
  \mathbf V \left(\mathbf{U}^T
  \mathbf U\right) \mathbf{V}^T
  \\
  &=
  \mathbf V \mathbf I \mathbf{V}^T
  \\
  &=
  \mathbf V \mathbf{V}^T
  \\
  &=
  \mathbf I
\end{align*}

due to the fact that the $\mathbf U$ and $\mathbf V$ factors that come out of the SVD are themselves orthogonal matrices.

Parameters
AThe tensor for which to find the closest orthogonal tensor.
Template Parameters
NumberThe type used to store the entries of the tensor. Must be either float or double.
Precondition
In order to use this function, this program must be linked with the LAPACK library.
A must not be singular. This is because, conceptually, the problem to be solved here is trying to find a matrix $\hat{\mathbf A}$ that minimizes some kind of distance from $\mathbf A$ while satisfying the quadratic constraint ${\hat {\mathbf A}}^T \hat {\mathbf A}={\mathbf I}$. This is not so dissimilar to the kind of problem where one wants to find a vector $\hat{\mathbf x}\in{\mathbb R}^n$ that minimizes the quadratic objective function $\|\hat {\mathbf x} - \mathbf x\|^2$ for a given $\mathbf x$ subject to the constraint $\|\mathbf x\|^2=1$ – in other words, we are seeking the point $\hat{\mathbf x}$ on the unit sphere that is closest to $\mathbf x$. This problem has a solution for all $\mathbf x$ except if $\mathbf x=0$. The corresponding condition for the problem we are considering here is that $\mathbf A$ must not have a zero eigenvalue.

Definition at line 81 of file tensor.cc.

◆ l1_norm()

template<int dim, typename Number>
Number l1_norm ( const Tensor< 2, dim, Number > & t)
related

Return the $l_1$ norm of the given rank-2 tensor, where $\|\mathbf T\|_1 = \max_j \sum_i |T_{ij}|$ (maximum of the sums over columns).

Definition at line 3039 of file tensor.h.

◆ linfty_norm()

template<int dim, typename Number>
Number linfty_norm ( const Tensor< 2, dim, Number > & t)
related

Return the $l_\infty$ norm of the given rank-2 tensor, where $\|\mathbf T\|_\infty = \max_i \sum_j |T_{ij}|$ (maximum of the sums over rows).

Definition at line 3065 of file tensor.h.