Physics::Notation::Kelvin Namespace Reference

A namespace with functions that assist in the conversion of vectors and tensors to and from a compressed format using Kelvin notation and weighting. More...

Functions
static ::ExceptionBase &	ExcNotationExcFullMatrixToTensorRowSize2 (int arg1, int arg2, int arg3)
static ::ExceptionBase &	ExcNotationExcFullMatrixToTensorRowSize3 (int arg1, int arg2, int arg3, int arg4)
static ::ExceptionBase &	ExcNotationExcFullMatrixToTensorColSize2 (int arg1, int arg2, int arg3)
static ::ExceptionBase &	ExcNotationExcFullMatrixToTensorColSize3 (int arg1, int arg2, int arg3, int arg4)

Detailed Description

A namespace with functions that assist in the conversion of vectors and tensors to and from a compressed format using Kelvin notation and weighting.

Both Kelvin and Voigt notation adopt the same indexing convention. With specific reference to the spatial dimension 3 case, for a rank-2 symmetric tensor \(\mathbf{S}\) we enumerate its tensor components

\[ \mathbf{S} \dealcoloneq \left[ \begin{array}{ccc} S_{00} & S_{01} & S_{02} \\ S_{10} = S_{01} & S_{11} & S_{12} \\ S_{20} = S_{02} & S_{21} = S_{12} & S_{22} \end{array} \right] \quad \Rightarrow \quad \left[ \begin{array}{ccc} n = 0 & n = 5 & n = 4 \\ sym & n = 1 & n = 3 \\ sym & sym & n = 2 \end{array} \right] , \]

where \(n\) denotes the Kelvin index for the tensor component, while for a general rank-2 tensor \(\mathbf{T}\)

\[ \mathbf{T} \dealcoloneq \left[ \begin{array}{ccc} T_{00} & T_{01} & T_{02} \\ T_{10} & T_{11} & T_{12} \\ T_{20} & T_{21} & T_{22} \end{array}\right] \quad \Rightarrow \quad \left[ \begin{array}{ccc} n = 0 & n = 5 & n = 4 \\ n = 6 & n = 1 & n = 3 \\ n = 7 & n = 8 & n = 2 \end{array}\right] , \]

and for a rank-1 tensor \(\mathbf{v}\)

\[ \mathbf{v} \dealcoloneq \left[ \begin{array}{c} v_{0} \\ v_{1} \\ v_{2} \end{array}\right] \quad \Rightarrow \quad \left[ \begin{array}{c} n = 0 \\ n = 1 \\ n = 2 \end{array}\right] . \]

To summarize, the relationship between tensor and Kelvin indices for both the three-dimensional case and the analogously discerned two-dimensional case outlined in the following table:

Dimension 2	Dimension 3
Tensor index pairs Kelvin index 00 0 11 1 12 2 21 3	Tensor index pairs Kelvin index 00 0 11 1 22 2 12 3 02 4 01 5 10 6 20 7 21 8

To illustrate the purpose of this notation, consider the rank-2 symmetric tensors \(\mathbf{S}\) and \(\mathbf{E}\) that are related to one another by \(\mathbf{S} = \cal{C} : \mathbf{E}\), where the operator \(\cal{C}\) is a fourth-order symmetric tensor. As opposed to the commonly used Voigt notation, Kelvin (or Mandel) notation keeps the same definition of the inner product \(\mathbf{S} : \mathbf{E}\) when both \(\mathbf{S}\) and \(\mathbf{E}\) are symmetric. In general, the inner product of all symmetric and general tensors remain the same regardless of the notation with which it is represented.

To achieve these two properties, namely that

\[ \mathbf{S} = \cal{C} : \mathbf{E} \quad \Rightarrow \quad \tilde{\mathbf{S}} = \tilde{\cal{C}} \; \tilde{\mathbf{E}} \]

and

\[ \mathbf{S} : \mathbf{E} \, \equiv \, \tilde{\mathbf{S}} \cdot \tilde{\mathbf{E}} , \]

it holds that the Kelvin-condensed equivalents of the previously defined symmetric tensors, indicated by the \(\tilde{\left(\bullet\right)}\), must be defined as

\[ \tilde{\mathbf{S}} = \left[ \begin{array}{c} S_{00} \\ S_{11} \\ S_{22} \\ \sqrt{2} S_{12} \\ \sqrt{2} S_{02} \\ \sqrt{2} S_{01} \end{array}\right] \quad \text{and} \quad \tilde{\mathbf{E}} = \left[ \begin{array}{c} E_{00} \\ E_{11} \\ E_{22} \\ \sqrt{2} E_{12} \\ \sqrt{2} E_{02} \\ \sqrt{2} E_{01} \end{array}\right] . \]

The corresponding and consistent condensed fourth-order symmetric tensor is

\[ \tilde{\cal{C}} = \left[ \begin{array}{cccccc} \tilde{\cal{C}}_{00} & \tilde{\cal{C}}_{01} & \tilde{\cal{C}}_{02} & \tilde{\cal{C}}_{03} & \tilde{\cal{C}}_{04} & \tilde{\cal{C}}_{05} \\ \tilde{\cal{C}}_{10} & \tilde{\cal{C}}_{11} & \tilde{\cal{C}}_{12} & \tilde{\cal{C}}_{13} & \tilde{\cal{C}}_{14} & \tilde{\cal{C}}_{15} \\ \tilde{\cal{C}}_{20} & \tilde{\cal{C}}_{21} & \tilde{\cal{C}}_{22} & \tilde{\cal{C}}_{23} & \tilde{\cal{C}}_{24} & \tilde{\cal{C}}_{25} \\ \tilde{\cal{C}}_{30} & \tilde{\cal{C}}_{31} & \tilde{\cal{C}}_{32} & \tilde{\cal{C}}_{33} & \tilde{\cal{C}}_{34} & \tilde{\cal{C}}_{35} \\ \tilde{\cal{C}}_{40} & \tilde{\cal{C}}_{41} & \tilde{\cal{C}}_{42} & \tilde{\cal{C}}_{43} & \tilde{\cal{C}}_{44} & \tilde{\cal{C}}_{45} \\ \tilde{\cal{C}}_{50} & \tilde{\cal{C}}_{51} & \tilde{\cal{C}}_{52} & \tilde{\cal{C}}_{53} & \tilde{\cal{C}}_{54} & \tilde{\cal{C}}_{55} \end{array}\right] \equiv \left[ \begin{array}{cccccc} {\cal{C}}_{0000} & {\cal{C}}_{0011} & {\cal{C}}_{0022} & \sqrt{2} {\cal{C}}_{0012} & \sqrt{2} {\cal{C}}_{0002} & \sqrt{2} {\cal{C}}_{0001} \\ {\cal{C}}_{1100} & {\cal{C}}_{1111} & {\cal{C}}_{1122} & \sqrt{2} {\cal{C}}_{1112} & \sqrt{2} {\cal{C}}_{1102} & \sqrt{2} {\cal{C}}_{1101} \\ {\cal{C}}_{2200} & {\cal{C}}_{2211} & {\cal{C}}_{2222} & \sqrt{2} {\cal{C}}_{2212} & \sqrt{2} {\cal{C}}_{2202} & \sqrt{2} {\cal{C}}_{2201} \\ \sqrt{2} {\cal{C}}_{1200} & \sqrt{2} {\cal{C}}_{1211} & \sqrt{2} {\cal{C}}_{1222} & 2 {\cal{C}}_{1212} & 2 {\cal{C}}_{1202} & 2 {\cal{C}}_{1201} \\ \sqrt{2} {\cal{C}}_{0200} & \sqrt{2} {\cal{C}}_{0211} & \sqrt{2} {\cal{C}}_{0222} & 2 {\cal{C}}_{0212} & 2 {\cal{C}}_{0202} & 2 {\cal{C}}_{0201} \\ \sqrt{2} {\cal{C}}_{0100} & \sqrt{2} {\cal{C}}_{0111} & \sqrt{2} {\cal{C}}_{0122} & 2 {\cal{C}}_{0112} & 2 {\cal{C}}_{0102} & 2 {\cal{C}}_{0101} \end{array}\right] . \]

The mapping from the two Kelvin indices of the FullMatrix \(\tilde{\cal{C}}\) to the rank-4 SymmetricTensor \(\cal{C}\) can be inferred using the table shown above.

An important observation is that both the left-hand side tensor \(\tilde{\mathbf{S}}\) and right-hand side tensor \(\tilde{\mathbf{E}}\) have the same form; this is a property that is not present in Voigt notation. The various factors introduced into \(\tilde{\mathbf{S}}\), \(\tilde{\mathbf{E}}\) and \(\tilde{\cal{C}}\) account for the symmetry of the tensors. The Kelvin description of their non-symmetric counterparts include no such factors.

Some useful references that show how this notation works include, amongst others,

@article{Nagel2016,
  author  = {Nagel, T. and G{\"o}rke, U-J. and Moerman, K. and Kolditz,
             O.},
  title   = {On advantages of the Kelvin mapping in finite element
             implementations of deformation processes},
  journal = {Environmental Earth Sciences},
  year    = {2016},
  volume  = {75},
  number  = {11},
  pages   = {937}
}

and

@article{Dellinger1998,
  author  = {Dellinger, J. and Vasicek, D. and Sondergeld, C.},
  title   = {Kelvin notation for stabilizing elastic-constant inversion},
  journal = {Revue de l'Institut Fran{\c{c}}ais du P{\'e}trole},
  year    = {1998},
  volume  = {53},
  number  = {5},
  pages   = {709--719},
  url     = {http://sepwww.stanford.edu/oldsep/joe/Reprints/8IWSA.pdf},
}

as well as the online reference found on this wikipedia page and the unit tests.

Author

Jean-Paul Pelteret, 2017

Function Documentation

to_vector() [1/5]

template<typename Number >

Vector<Number> Physics::Notation::Kelvin::to_vector

(

const Number &

s

)

Convert a scalar value to its compressed vector equivalent.

The output vector has one entry.

to_vector() [2/5]

template<int dim, typename Number >

Vector<Number> Physics::Notation::Kelvin::to_vector

(

const Tensor< 0, dim, Number > &

s

)

Convert a rank-0 tensor to its compressed vector equivalent.

The output vector has one entry.

to_vector() [3/5]

template<int dim, typename Number >

Vector<Number> Physics::Notation::Kelvin::to_vector

(

const Tensor< 1, dim, Number > &

v

)

Convert a rank-1 tensor to its compressed vector equivalent.

The output vector has \(dim\) entries.

to_vector() [4/5]

template<int dim, typename Number >

Vector<Number> Physics::Notation::Kelvin::to_vector

(

const Tensor< 2, dim, Number > &

t

)

Convert a rank-2 tensor to its compressed vector equivalent.

The output vector has Tensor<2,dim>::n_independent_components entries.

to_vector() [5/5]

template<int dim, typename Number >

Vector<Number> Physics::Notation::Kelvin::to_vector

(

const SymmetricTensor< 2, dim, Number > &

st

)

Convert a rank-2 symmetric tensor to its compressed vector equivalent.

The output vector has SymmetricTensor<2,dim>::n_independent_components entries.

to_matrix() [1/8]

template<typename Number >

FullMatrix<Number> Physics::Notation::Kelvin::to_matrix

(

const Number &

s

)

Convert a scalar value to its compressed matrix equivalent.

The output matrix will have one row and one column.

to_matrix() [2/8]

template<int dim, typename Number >

FullMatrix<Number> Physics::Notation::Kelvin::to_matrix

(

const Tensor< 0, dim, Number > &

s

)

Convert a rank-0 tensor to its compressed matrix equivalent.

The output matrix will have one row and one column.

to_matrix() [3/8]

template<int dim, typename Number >

FullMatrix<Number> Physics::Notation::Kelvin::to_matrix

(

const Tensor< 1, dim, Number > &

v

)

Convert a rank-1 tensor to its compressed matrix equivalent.

The output matrix will have \(dim\) rows and one column.

to_matrix() [4/8]

template<int dim, typename Number >

FullMatrix<Number> Physics::Notation::Kelvin::to_matrix

(

const Tensor< 2, dim, Number > &

t

)

Convert a rank-2 tensor to its compressed matrix equivalent.

The output matrix will have \(dim\) rows and \(dim\) columns.

to_matrix() [5/8]

template<int dim, typename Number >

FullMatrix<Number> Physics::Notation::Kelvin::to_matrix

(

const SymmetricTensor< 2, dim, Number > &

st

)

Convert a rank-2 symmetric tensor to its compressed matrix equivalent.

The output matrix will have \(dim\) rows and \(dim\) columns, with the same format as the equivalent function for non-symmetric tensors. This is because it is not possible to compress the SymmetricTensor<2,dim>::n_independent_components unique entries into a square matrix.

to_matrix() [6/8]

template<int dim, typename SubTensor1 = Tensor<2, dim>, typename SubTensor2 = Tensor<1, dim>, typename Number >

FullMatrix<Number> Physics::Notation::Kelvin::to_matrix

(

const Tensor< 3, dim, Number > &

t

)

Convert a rank-3 tensor to its compressed matrix equivalent.

The template arguments SubTensor1 and SubTensor2 determine how the unrolling occurs, in particular how the elements of the rank-3 tensor are to be interpreted.

So, for example, with the following two conversions

Tensor<3,dim> r3_tnsr;      // All elements filled differently
Tensor<3,dim> r3_symm_tnsr; // Some elements filled symmetrically
 
const FullMatrix<double> mtrx_1 =
  Physics::Notation::to_matrix<dim,
                               Tensor<2,dim>,
                               Tensor<1,dim>*>(r3_tnsr);
const FullMatrix<double> mtrx_2 =
  Physics::Notation::to_matrix<dim,
                               Tensor<1,dim>,
                               SymmetricTensor<2,dim>*>(r3_symm_tnsr);

the matrix mtrx_1 will have \(dim \times dim\) rows and \(dim\) columns (i.e. size Tensor<2,dim>::n_independent_components \(\times\) Tensor<1,dim>::n_independent_components), while those of the matrix mtrx_2 will have \(dim\) rows and \((dim \times dim + dim)/2\) columns (i.e. size Tensor<1,dim>::n_independent_components \(\times\) SymmetricTensor<2,dim>::n_independent_components), as it is assumed that the entries corresponding to the alternation of the second and third indices are equal. That is to say that r3_symm_tnsr[i][j][k] == r3_symm_tnsr[i][k][j].

to_matrix() [7/8]

template<int dim, typename Number >

FullMatrix<Number> Physics::Notation::Kelvin::to_matrix

(

const Tensor< 4, dim, Number > &

t

)

Convert a rank-4 tensor to its compressed matrix equivalent.

The output matrix will have Tensor<2,dim>::n_independent_components rows and Tensor<2,dim>::n_independent_components columns.

to_matrix() [8/8]

template<int dim, typename Number >

FullMatrix<Number> Physics::Notation::Kelvin::to_matrix

(

const SymmetricTensor< 4, dim, Number > &

st

)

Convert a rank-4 symmetric tensor to its compressed matrix equivalent.

The output matrix will have SymmetricTensor<2,dim>::n_independent_components rows and SymmetricTensor<2,dim>::n_independent_components columns.

to_tensor() [1/15]

template<typename Number >

void Physics::Notation::Kelvin::to_tensor	(	const Vector< Number > &	vec,
		Number &	s
	)

Convert a compressed vector to its equivalent scalar value.

to_tensor() [2/15]

template<int dim, typename Number >

void Physics::Notation::Kelvin::to_tensor	(	const Vector< Number > &	vec,
		Tensor< 0, dim, Number > &	s
	)

Convert a compressed vector to its equivalent rank-0 tensor.

to_tensor() [3/15]

template<int dim, typename Number >

void Physics::Notation::Kelvin::to_tensor	(	const Vector< Number > &	vec,
		Tensor< 1, dim, Number > &	v
	)

Convert a compressed vector to its equivalent rank-1 tensor.

to_tensor() [4/15]

template<int dim, typename Number >

void Physics::Notation::Kelvin::to_tensor	(	const Vector< Number > &	vec,
		Tensor< 2, dim, Number > &	t
	)

Convert a compressed vector to its equivalent rank-2 tensor.

to_tensor() [5/15]

template<int dim, typename Number >

void Physics::Notation::Kelvin::to_tensor	(	const Vector< Number > &	vec,
		SymmetricTensor< 2, dim, Number > &	st
	)

Convert a compressed vector to its equivalent rank-2 symmetric tensor.

to_tensor() [6/15]

template<typename Number >

void Physics::Notation::Kelvin::to_tensor	(	const FullMatrix< Number > &	mtrx,
		Number &	s
	)

Convert a compressed matrix to its equivalent scalar value.

to_tensor() [7/15]

template<int dim, typename Number >

void Physics::Notation::Kelvin::to_tensor	(	const FullMatrix< Number > &	mtrx,
		Tensor< 0, dim, Number > &	s
	)

Convert a compressed matrix to its equivalent rank-0 tensor.

to_tensor() [8/15]

template<int dim, typename Number >

void Physics::Notation::Kelvin::to_tensor	(	const FullMatrix< Number > &	mtrx,
		Tensor< 1, dim, Number > &	v
	)

Convert a compressed matrix to its equivalent rank-1 tensor.

to_tensor() [9/15]

template<int dim, typename Number >

void Physics::Notation::Kelvin::to_tensor	(	const FullMatrix< Number > &	mtrx,
		Tensor< 2, dim, Number > &	t
	)

Convert a compressed matrix to its equivalent rank-2 tensor.

to_tensor() [10/15]

template<int dim, typename Number >

void Physics::Notation::Kelvin::to_tensor	(	const FullMatrix< Number > &	mtrx,
		SymmetricTensor< 2, dim, Number > &	st
	)

Convert a compressed matrix to its equivalent rank-2 symmetric tensor.

to_tensor() [11/15]

template<int dim, typename Number >

void Physics::Notation::Kelvin::to_tensor	(	const FullMatrix< Number > &	mtrx,
		Tensor< 3, dim, Number > &	t
	)

Convert a compressed matrix to its equivalent rank-3 tensor.

Note

Based on the size of the matrix mtrx, some of the components of t may be interpreted as having symmetric counterparts. This is the reverse of the operation explained in the documentation of the counterpart to_matrix() function.

to_tensor() [12/15]

template<int dim, typename Number >

void Physics::Notation::Kelvin::to_tensor	(	const FullMatrix< Number > &	mtrx,
		Tensor< 4, dim, Number > &	t
	)

Convert a compressed matrix to its equivalent rank-4 tensor.

to_tensor() [13/15]

template<int dim, typename Number >

void Physics::Notation::Kelvin::to_tensor	(	const FullMatrix< Number > &	mtrx,
		SymmetricTensor< 4, dim, Number > &	st
	)

Convert a compressed matrix to its equivalent rank-4 symmetric tensor.

to_tensor() [14/15]

template<typename TensorType , typename Number >

TensorType Physics::Notation::Kelvin::to_tensor

(

const Vector< Number > &

vec

)

A generic helper function that will convert a compressed vector to its equivalent TensorType.

to_tensor() [15/15]

template<typename TensorType , typename Number >

TensorType Physics::Notation::Kelvin::to_tensor

(

const FullMatrix< Number > &

vec

)

A generic helper function that will convert a compressed matrix to its equivalent TensorType.