Reference documentation for deal.II version Git 053e5b2 2017-07-21 22:33:36 -0600
TensorProductMatrixSymmetricSum< dim, Number, size > Class Template Reference

#include <deal.II/lac/tensor_product_matrix.h>

Public Member Functions

TensorProductMatrixSymmetricSum ()

TensorProductMatrixSymmetricSum (const FullMatrix< Number > &mass_matrix, const FullMatrix< Number > &derivative_matrix)

void reinit (const FullMatrix< Number > &mass_matrix, const FullMatrix< Number > &derivative_matrix)

unsigned int m () const

unsigned int n () const

void vmult (Vector< Number > &dst, const Vector< Number > &src) const

void vmult (Number *dst, const Number *src) const

void apply_inverse (Vector< Number > &dst, const Vector< Number > &src) const

void apply_inverse (Number *dst, const Number *src) const

Private Attributes

FullMatrix< Number > mass_matrix

FullMatrix< Number > derivative_matrix

AlignedVector< Number > eigenvalues

Table< 2, Number > eigenvectors

AlignedVector< Number > tmp_array

Detailed Description

template<int dim, typename Number, int size = -1> class TensorProductMatrixSymmetricSum< dim, Number, size >

This is a special matrix class defined as the tensor product (or Kronecker product) of 1D matrices of the type

\begin{align*} L &= A \otimes M + M \otimes A \end{align*}

in 2D and

\begin{align*} L &= A \otimes M \otimes M + M \otimes A \otimes M + M \otimes M \otimes A \end{align*}

in 3D. The typical application setting is a discretization of the Laplacian $$L$$ on a Cartesian (axis-aligned) geometry, where it can be exactly represented by the Kronecker or tensor product of a 1D mass matrix $$M$$ and a 1D Laplace matrix $$A$$ in each dimension. The dimension of the resulting class is the product of the one-dimensional matrices.

This class implements two basic operations, namely the usual multiplication by a vector and the inverse. For both operations, fast tensorial techniques can be applied that implement the operator evaluation in $$\text{size}(M)^{d+1}$$ arithmetic operations, considerably less than $$\text{size}(M)^{2d}$$ for the naive forward transformation and $$\text{size}(M)^{3d}$$ for setting up the inverse of $$L$$.

Interestingly, the exact inverse of the matrix $$L$$ can be found through tensor products due to an article by R. E. Lynch, J. R. Rice, D. H. Thomas, Direct solution of partial difference equations by tensor product methods, Numerische Mathematik 6, 185-199 from 1964,

\begin{align*} L^{-1} &= S \otimes S (\Lambda \otimes I + I \otimes \Lambda)^{-1} S^\mathrm T \otimes S^\mathrm T, \end{align*}

where $$S$$ is the matrix of eigenvectors to the generalized eigenvalue problem

\begin{align*} A s &= \lambda M s, \end{align*}

and $$\Lambda$$ is the diagonal matrix representing the generalized eigenvalues $$\lambda$$. Note that the vectors $$s$$ are such that they simultaneously diagonalize $$A$$ and $$M$$, $$S^{\mathrm T} A S = \Lambda$$ and $$S^{\mathrm T} B S = I$$. This method of matrix inversion is called fast diagonalization method.

This class requires LAPACK support.

Note that this class allows for two modes of usage. The first is a use case with run time constants for the matrix dimensions that is achieved by setting the optional template parameter for the size to -1. The second mode of usage that is faster allows to set the template parameter as a compile time constant, giving significantly faster code in particular for small sizes of the matrix.

Note
This class uses a temporary array for storing intermediate results that is a class member. A mutex is used to protect access to this array and ensure correct results. If several threads run parallel instances of this class, it is recommended that each threads holds its own matrix version.
Template Parameters
 dim Dimension of the problem. Currently, 1D, 2D, and 3D codes are implemented. Number Type of the underlying array elements. Note that the underlying LAPACK implementation supports only float and double numbers, so only these two types are currently supported. size Compile-time array lengths. By default at -1, which means that the run-time info stored in the matrices passed to the reinit() function is used.

Definition at line 100 of file tensor_product_matrix.h.

Constructor & Destructor Documentation

template<int dim, typename Number, int size = -1>
 TensorProductMatrixSymmetricSum< dim, Number, size >::TensorProductMatrixSymmetricSum ( )

Constructor.

template<int dim, typename Number, int size = -1>
 TensorProductMatrixSymmetricSum< dim, Number, size >::TensorProductMatrixSymmetricSum ( const FullMatrix< Number > & mass_matrix, const FullMatrix< Number > & derivative_matrix )

Constructor that is equivalent to the previous constructor and immediately calling reinit().

Member Function Documentation

template<int dim, typename Number, int size = -1>
 void TensorProductMatrixSymmetricSum< dim, Number, size >::reinit ( const FullMatrix< Number > & mass_matrix, const FullMatrix< Number > & derivative_matrix )

Initializes the matrix to the given mass matrix $$M$$ and derivative matrix $$A$$. Note that the current implementation requires $$M$$ to be symmetric and positive definite and $$A$$ to be symmetric and invertible but not necessarily positive defininte.

template<int dim, typename Number, int size = -1>
 unsigned int TensorProductMatrixSymmetricSum< dim, Number, size >::m ( ) const

Returns the number of rows of this matrix, given by the dim-th power of the size of the 1D matrices passed to the constructor.

template<int dim, typename Number, int size = -1>
 unsigned int TensorProductMatrixSymmetricSum< dim, Number, size >::n ( ) const

Returns the number of columns of this matrix, given by the dim-th power of the size of the 1D matrices passed to the constructor.

template<int dim, typename Number, int size = -1>
 void TensorProductMatrixSymmetricSum< dim, Number, size >::vmult ( Vector< Number > & dst, const Vector< Number > & src ) const

Implements a matrix-vector product with the underlying matrix as described in the main documentation of this class.

template<int dim, typename Number, int size = -1>
 void TensorProductMatrixSymmetricSum< dim, Number, size >::vmult ( Number * dst, const Number * src ) const

Implements a matrix-vector product with the underlying matrix as described in the main documentation of this class. Same as the other vmult() function, but operating on plain pointers rather than a vector (no check of array bounds possible).

template<int dim, typename Number, int size = -1>
 void TensorProductMatrixSymmetricSum< dim, Number, size >::apply_inverse ( Vector< Number > & dst, const Vector< Number > & src ) const

Implements a matrix-vector product with the underlying matrix as described in the main documentation of this class.

template<int dim, typename Number, int size = -1>
 void TensorProductMatrixSymmetricSum< dim, Number, size >::apply_inverse ( Number * dst, const Number * src ) const

Implements a matrix-vector product with the underlying matrix as described in the main documentation of this class. Same as the other apply_inverse() function, but operating on plain pointers rather than a vector (no check of array bounds possible).

Member Data Documentation

template<int dim, typename Number, int size = -1>
 FullMatrix TensorProductMatrixSymmetricSum< dim, Number, size >::mass_matrix
private

A copy of the mass_matrix object passed to the reinit() method.

Definition at line 172 of file tensor_product_matrix.h.

template<int dim, typename Number, int size = -1>
 FullMatrix TensorProductMatrixSymmetricSum< dim, Number, size >::derivative_matrix
private

A copy of the derivative_matrix object passed to the reinit() method.

Definition at line 177 of file tensor_product_matrix.h.

template<int dim, typename Number, int size = -1>
 AlignedVector TensorProductMatrixSymmetricSum< dim, Number, size >::eigenvalues
private

A vector containing the generalized eigenvalues of A s = lambda B s.

Definition at line 182 of file tensor_product_matrix.h.

template<int dim, typename Number, int size = -1>
 Table<2,Number> TensorProductMatrixSymmetricSum< dim, Number, size >::eigenvectors
private

The matrix containing the generalized eigenvectors.

Definition at line 187 of file tensor_product_matrix.h.

template<int dim, typename Number, int size = -1>
 AlignedVector TensorProductMatrixSymmetricSum< dim, Number, size >::tmp_array
mutableprivate

An array for temporary data.

Definition at line 192 of file tensor_product_matrix.h.

template<int dim, typename Number, int size = -1>
 Threads::Mutex TensorProductMatrixSymmetricSum< dim, Number, size >::mutex
mutableprivate

A mutex that guards access to the array tmp_array.

Definition at line 197 of file tensor_product_matrix.h.

The documentation for this class was generated from the following file: