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

Inheritance diagram for BlockMatrixArray< number, BlockVectorType >:

Classes
class	Entry

Public Types
using	size_type = types::global_dof_index

Public Member Functions
	BlockMatrixArray ()

	BlockMatrixArray (const unsigned int n_block_rows, const unsigned int n_block_cols)

void	initialize (const unsigned int n_block_rows, const unsigned int n_block_cols)

void	reinit (const unsigned int n_block_rows, const unsigned int n_block_cols)

template<typename MatrixType >
void	enter (const MatrixType &matrix, const unsigned int row, const unsigned int col, const number prefix=1., const bool transpose=false)

void	clear ()

unsigned int	n_block_rows () const

unsigned int	n_block_cols () const

void	vmult (BlockVectorType &dst, const BlockVectorType &src) const

void	vmult_add (BlockVectorType &dst, const BlockVectorType &src) const

void	Tvmult (BlockVectorType &dst, const BlockVectorType &src) const

void	Tvmult_add (BlockVectorType &dst, const BlockVectorType &src) const

number	matrix_scalar_product (const BlockVectorType &u, const BlockVectorType &v) const

number	matrix_norm_square (const BlockVectorType &u) const

template<class StreamType >
void	print_latex (StreamType &out) const

Public Member Functions inherited from Subscriptor
	Subscriptor ()

	Subscriptor (const Subscriptor &)

	Subscriptor (Subscriptor &&) noexcept

virtual	~Subscriptor ()

Subscriptor &	operator= (const Subscriptor &)

Subscriptor &	operator= (Subscriptor &&) noexcept

void	subscribe (std::atomic< bool > *const validity, const std::string &identifier="") const

void	unsubscribe (std::atomic< bool > *const validity, const std::string &identifier="") const

unsigned int	n_subscriptions () const

template<typename StreamType >
void	list_subscribers (StreamType &stream) const

void	list_subscribers () const

template<class Archive >
void	serialize (Archive &ar, const unsigned int version)

Protected Attributes
std::vector< Entry >	entries

Private Attributes
unsigned int	block_rows

unsigned int	block_cols

Additional Inherited Members
Static Public Member Functions inherited from Subscriptor
static ::ExceptionBase &	ExcInUse (int arg1, std::string arg2, std::string arg3)

static ::ExceptionBase &	ExcNoSubscriber (std::string arg1, std::string arg2)

Detailed Description

template<typename number = double, typename BlockVectorType = BlockVector<number>>
class BlockMatrixArray< number, BlockVectorType >

Block matrix composed of different single matrices; these matrices may even be of different types.

Given a set of arbitrary matrices A_i, this class implements a block matrix with block entries of the form M_jk = s_jkA_i. Each A_i may be used several times with different prefix. The matrices are not copied into the BlockMatrixArray object, but rather a PointerMatrix referencing each of them will be stored along with factors and transposition flags.

Non-zero entries are registered by the function enter(), zero entries are not stored at all. Using enter() with the same location (i,j) several times will add the corresponding matrices in matrix-vector multiplications. These matrices will not be actually added, but the multiplications with them will be summed up.

Note: This mechanism makes it impossible to access single entries of BlockMatrixArray. In particular, (block) relaxation preconditioners based on PreconditionRelaxation or PreconditionBlock cannot be used with this class. If you need a preconditioner for a BlockMatrixArray object, use BlockTrianglePrecondition.

Requirements on MatrixType

The template argument MatrixType is a class providing the matrix- vector multiplication functions vmult(), Tvmult(), vmult_add() and Tvmult_add() used in this class, but with arguments of type Vector<number> instead of BlockVector<number>. Every matrix which can be used by PointerMatrix is allowed, in particular SparseMatrix is a possible entry type.

Example program

We document the relevant parts of examples/doxygen/block_matrix_array.cc.

Obviously, we have to include the header file containing the definition of BlockMatrixArray:

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

First, we set up some matrices to be entered into the blocks.

int main()
{
  FullMatrix<float> A(4, 4);
  FullMatrix<float> B1(4, 2);
  FullMatrix<float> B2(2, 4);
  FullMatrix<float> C(2, 2);
  A.fill(&Adata[0][0]);
  B1.fill(&B1data[0][0]);
  B2.fill(&B2data[0][0]);
  C.fill(&Cdata[0][0]);

Now, we are ready to build a 2x2 BlockMatrixArray.

BlockMatrixArray<double> matrix(2, 2);

First, we enter the matrix A multiplied by 2 in the upper left block

matrix.enter(A, 0, 0, 2.);

Now -1 times B1 in the upper right block.

matrix.enter(B1, 0, 1, -1.);

We add the transpose of B2 to the upper right block and continue in a similar fashion. In the end, the block matrix structure is printed into an LaTeX table.

  matrix.enter(B2, 0, 1, 1., true);
  matrix.enter(B2, 1, 0, 1.);
  matrix.enter(B1, 1, 0, -1., true);
  matrix.enter(C, 1, 1);
  matrix.print_latex(deallog);

Now, we set up vectors to be multiplied with this matrix and do a multiplication.

  std::vector<unsigned int> block_sizes(2);
  block_sizes[0] = 4;
  block_sizes[1] = 2;
  BlockVector<double> result(block_sizes);
  BlockVector<double> x(block_sizes);
  BlockVector<double> y(block_sizes);
  for (unsigned int i = 0; i < result.size(); ++i)
    result(i) = i;
  matrix.vmult(y, result);

Finally, we solve a linear system with BlockMatrixArray, using no preconditioning and the conjugate gradient method.

  SolverControl        control(100, 1.e-10);
  PreconditionIdentity id;
  SolverCG<BlockVector<double>> cg(control);
  cg.solve(matrix, x, y, id);
  x.add(-1., result);
  deallog << "Error " << x.l2_norm() << std::endl;

The remaining code of this sample program concerns preconditioning and is described in the documentation of BlockTrianglePrecondition.

Deprecated:: This class has been superseded by BlockLinearOperator.

See also: Block (linear algebra)

Author: Guido Kanschat

Date: 2000-2005, 2010

Definition at line 118 of file block_matrix_array.h.

Member Typedef Documentation

◆ size_type

template<typename number = double, typename BlockVectorType = BlockVector<number>>

using BlockMatrixArray< number, BlockVectorType >::size_type = types::global_dof_index

Declare the type for container size.

Definition at line 124 of file block_matrix_array.h.

Constructor & Destructor Documentation

◆ BlockMatrixArray() [1/2]

template<typename number , typename BlockVectorType >

BlockMatrixArray< number, BlockVectorType >::BlockMatrixArray ( )

Default constructor creating a useless object. initialize() must be called before using it.

Definition at line 49 of file block_matrix_array.cc.

◆ BlockMatrixArray() [2/2]

template<typename number , typename BlockVectorType >

BlockMatrixArray< number, BlockVectorType >::BlockMatrixArray	(	const unsigned int	n_block_rows,
		const unsigned int	n_block_cols
	)

Constructor fixing the dimensions.

Definition at line 57 of file block_matrix_array.cc.

Member Function Documentation

◆ initialize()

template<typename number , typename BlockVectorType >

void BlockMatrixArray< number, BlockVectorType >::initialize	(	const unsigned int	n_block_rows,
		const unsigned int	n_block_cols
	)

Initialize object completely. This is the function to call for an object created by the default constructor.

Definition at line 67 of file block_matrix_array.cc.

◆ reinit()

template<typename number , typename BlockVectorType >

void BlockMatrixArray< number, BlockVectorType >::reinit	(	const unsigned int	n_block_rows,
		const unsigned int	n_block_cols
	)

Adjust the matrix to a new size and delete all blocks.

Definition at line 79 of file block_matrix_array.cc.

◆ enter()

template<typename number = double, typename BlockVectorType = BlockVector<number>>

template<typename MatrixType >

void BlockMatrixArray< number, BlockVectorType >::enter	(	const MatrixType &	matrix,
		const unsigned int	row,
		const unsigned int	col,
		const number	prefix = `1.`,
		const bool	transpose = `false`
	)

Add a block matrix entry. The matrix is entered into a list of blocks for multiplication, together with its coordinates row and col as well as optional multiplication factor prefix and transpose flag transpose.

Note: No check for consistency of block sizes is made. Therefore, entering a block of wrong dimension here will only lead to a ExcDimensionMismatch in one of the multiplication functions.

◆ clear()

template<typename number , typename BlockVectorType >

void BlockMatrixArray< number, BlockVectorType >::clear ( )

Delete all entries, i.e. reset the matrix to an empty state.

Definition at line 92 of file block_matrix_array.cc.

◆ n_block_rows()

template<typename number , typename BlockVectorType >

unsigned int BlockMatrixArray< number, BlockVectorType >::n_block_rows ( ) const

Number of block-entries per column.

Definition at line 239 of file block_matrix_array.cc.

◆ n_block_cols()

template<typename number , typename BlockVectorType >

unsigned int BlockMatrixArray< number, BlockVectorType >::n_block_cols ( ) const

Number of block-entries per row.

Definition at line 248 of file block_matrix_array.cc.

◆ vmult()

template<typename number , typename BlockVectorType >

void BlockMatrixArray< number, BlockVectorType >::vmult	(	BlockVectorType &	dst,
		const BlockVectorType &	src
	)		const

Matrix-vector multiplication.

Definition at line 132 of file block_matrix_array.cc.

◆ vmult_add()

template<typename number , typename BlockVectorType >

void BlockMatrixArray< number, BlockVectorType >::vmult_add	(	BlockVectorType &	dst,
		const BlockVectorType &	src
	)		const

Matrix-vector multiplication adding to dst.

Definition at line 100 of file block_matrix_array.cc.

◆ Tvmult()

template<typename number , typename BlockVectorType >

void BlockMatrixArray< number, BlockVectorType >::Tvmult	(	BlockVectorType &	dst,
		const BlockVectorType &	src
	)		const

Transposed matrix-vector multiplication.

Definition at line 176 of file block_matrix_array.cc.

◆ Tvmult_add()

template<typename number , typename BlockVectorType >

void BlockMatrixArray< number, BlockVectorType >::Tvmult_add	(	BlockVectorType &	dst,
		const BlockVectorType &	src
	)		const

Transposed matrix-vector multiplication adding to dst.

Definition at line 144 of file block_matrix_array.cc.

◆ matrix_scalar_product()

template<typename number , typename BlockVectorType >

number BlockMatrixArray< number, BlockVectorType >::matrix_scalar_product	(	const BlockVectorType &	u,
		const BlockVectorType &	v
	)		const

Matrix scalar product between two vectors (at least for a symmetric matrix).

Definition at line 188 of file block_matrix_array.cc.

◆ matrix_norm_square()

template<typename number , typename BlockVectorType >

number BlockMatrixArray< number, BlockVectorType >::matrix_norm_square ( const BlockVectorType & u ) const

Compute \(u^T M u\). This is the square of the norm induced by the matrix assuming the matrix is symmetric positive definitive.

Definition at line 229 of file block_matrix_array.cc.

◆ print_latex()

template<typename number = double, typename BlockVectorType = BlockVector<number>>

template<class StreamType >

void BlockMatrixArray< number, BlockVectorType >::print_latex ( StreamType & out ) const

Print the block structure as a LaTeX-array. This output will not be very intuitive, since the current object lacks knowledge about what the individual blocks represent or how they should be named. Instead, what you will see is an entry for each block showing all the matrices with their multiplication factors and possibly transpose marks. The matrices itself are named successively as they are encountered. If the same matrix is entered several times, it will be listed with different names.

As an example, consider the following code:

FullMatrix<double> A1(4,4);
FullMatrix<double> A2(4,4);
FullMatrix<double> B(4,3);
FullMatrix<double> C(3,3);
BlockMatrixArray<double> block(2,2);
block.enter(A1,0,0);
block.enter(A2,0,0,2,true);
block.enter(B,0,1,-3.);
block.enter(B,0,1,-3.,true);
block.enter(C,1,1,1.,true);
block.print_latex(std::cout);

The current function will then produce output of the following kind:

\begin{array}{cc}
   M0+2xM1^T &     -3xM2-3xM3^T\\
             &      M4^T
\end{array}

Note how the individual blocks here are just numbered successively as M0 to M4 and that the output misses the fact that M2 and M3 are, in fact, the same matrix. Nevertheless, the output at least gives some kind of idea of the block structure of this matrix.

Member Data Documentation

◆ entries

template<typename number = double, typename BlockVectorType = BlockVector<number>>

std::vector<Entry> BlockMatrixArray< number, BlockVectorType >::entries

protected

Array of block entries in the matrix.

Definition at line 347 of file block_matrix_array.h.

◆ block_rows

template<typename number = double, typename BlockVectorType = BlockVector<number>>

unsigned int BlockMatrixArray< number, BlockVectorType >::block_rows

private

Number of blocks per column.

Definition at line 353 of file block_matrix_array.h.

◆ block_cols

template<typename number = double, typename BlockVectorType = BlockVector<number>>

unsigned int BlockMatrixArray< number, BlockVectorType >::block_cols

private

number of blocks per row.

Definition at line 357 of file block_matrix_array.h.

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

deal.II/lac/block_matrix_array.h
source/lac/block_matrix_array.cc

Classes

Public Types

Public Member Functions

Protected Attributes

Private Attributes

Additional Inherited Members

Detailed Description

template<typename number = double, typename BlockVectorType = BlockVector<number>> class BlockMatrixArray< number, BlockVectorType >

Requirements on MatrixType

Example program

Member Typedef Documentation

◆ size_type

Constructor & Destructor Documentation

◆ BlockMatrixArray() [1/2]

◆ BlockMatrixArray() [2/2]

Member Function Documentation

◆ initialize()

◆ reinit()

◆ enter()

◆ clear()

◆ n_block_rows()

◆ n_block_cols()

◆ vmult()

◆ vmult_add()

◆ Tvmult()

◆ Tvmult_add()

◆ matrix_scalar_product()

◆ matrix_norm_square()

◆ print_latex()

Member Data Documentation

◆ entries

◆ block_rows

◆ block_cols

template<typename number = double, typename BlockVectorType = BlockVector<number>>
class BlockMatrixArray< number, BlockVectorType >