BlockMatrixArray< number > Class Template Reference
[Derived matrices]

Inheritance diagram for BlockMatrixArray< number >:
Inheritance graph
[legend]

List of all members.

Classes

class  Entry

Public Member Functions

 BlockMatrixArray ()
 BlockMatrixArray (const unsigned int n_block_rows, const unsigned int n_block_cols, VectorMemory< Vector< number > > &mem)
void initialize (const unsigned int n_block_rows, const unsigned int n_block_cols, VectorMemory< Vector< number > > &mem)
void reinit (const unsigned int n_block_rows, const unsigned int n_block_cols)
template<class MATRIX >
void enter (const MATRIX &matrix, const unsigned int row, const unsigned int col, const double prefix=1., const bool transpose=false)
template<class MATRIX >
void enter_aux (VectorMemory< Vector< number > > &mem, const MATRIX &matrix, const unsigned int row, const unsigned int col, const double prefix=1., const bool transpose=false)
void clear ()
unsigned int n_block_rows () const
unsigned int n_block_cols () const
void vmult (BlockVector< number > &dst, const BlockVector< number > &src) const
void vmult_add (BlockVector< number > &dst, const BlockVector< number > &src) const
void Tvmult (BlockVector< number > &dst, const BlockVector< number > &src) const
void Tvmult_add (BlockVector< number > &dst, const BlockVector< number > &src) const
number matrix_scalar_product (const BlockVector< number > &u, const BlockVector< number > &v) const
number matrix_norm_square (const BlockVector< number > &u) const
template<class STREAM >
void print_latex (STREAM &out) const

Protected Attributes

std::vector< Entryentries
SmartPointer< VectorMemory
< Vector< number > > > 
mem

Private Attributes

unsigned int block_rows
unsigned int block_cols

Detailed Description

template<typename number = double>
class BlockMatrixArray< number >

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

Given a set of arbitrary matrices Ai, this class implements a block matrix with block entries of the form Mjk = sjkAi. Each Ai 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 MATRIX

The template argument MATRIX 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 <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);
  B1.fill(B1data);
  B2.fill(B2data);
  C.fill(Cdata);

The BlockMatrixArray needs a VectorMemory<Vector<number> > object to allocate auxiliary vectors. number must equal the second template argument of BlockMatrixArray and also the number type of the BlockVector used later. We use the GrowingVectorMemory type, since it remembers the vector and avoids reallocating.

@ line Growing

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

First, we enter the matrix A multiplied by 2 in the upper left block
Now -1 times B1 in the upper right block.
  matrix.enter(A,0,0,2.);
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(B1,0,1,-1.);
  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);
  GrowingVectorMemory<BlockVector<double> > mem;
  PreconditionIdentity id;

  SolverCG<BlockVector<double> > cg(control, mem);
  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.

Author:
Guido Kanschat, 2000 - 2005

Constructor & Destructor Documentation

template<typename number = double>
BlockMatrixArray< number >::BlockMatrixArray (  ) 

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

template<typename number = double>
BlockMatrixArray< number >::BlockMatrixArray ( const unsigned int  n_block_rows,
const unsigned int  n_block_cols,
VectorMemory< Vector< number > > &  mem 
)

Constructor fixing the dimensions.


Member Function Documentation

template<typename number = double>
void BlockMatrixArray< number >::initialize ( const unsigned int  n_block_rows,
const unsigned int  n_block_cols,
VectorMemory< Vector< number > > &  mem 
)

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

template<typename number = double>
void BlockMatrixArray< number >::reinit ( const unsigned int  n_block_rows,
const unsigned int  n_block_cols 
)

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

template<typename number = double>
template<class MATRIX >
void BlockMatrixArray< number >::enter ( const MATRIX &  matrix,
const unsigned int  row,
const unsigned int  col,
const double  prefix = 1.,
const bool  transpose = false 
) [inline]

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.

Reimplemented in BlockTrianglePrecondition< number >.

template<typename number = double>
template<class MATRIX >
void BlockMatrixArray< number >::enter_aux ( VectorMemory< Vector< number > > &  mem,
const MATRIX &  matrix,
const unsigned int  row,
const unsigned int  col,
const double  prefix = 1.,
const bool  transpose = false 
) [inline]

Add an entry like with enter, but use PointerMatrixAux for matrices not having functions vmult_add() and TVmult_add().

template<typename number = double>
void BlockMatrixArray< number >::clear (  ) 

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

template<typename number = double>
unsigned int BlockMatrixArray< number >::n_block_rows (  )  const

Number of block-entries per column.

template<typename number = double>
unsigned int BlockMatrixArray< number >::n_block_cols (  )  const

Number of block-entries per row.

template<typename number = double>
void BlockMatrixArray< number >::vmult ( BlockVector< number > &  dst,
const BlockVector< number > &  src 
) const

Matrix-vector multiplication.

Reimplemented in BlockTrianglePrecondition< number >.

template<typename number = double>
void BlockMatrixArray< number >::vmult_add ( BlockVector< number > &  dst,
const BlockVector< number > &  src 
) const

Matrix-vector multiplication adding to dst.

Reimplemented in BlockTrianglePrecondition< number >.

template<typename number = double>
void BlockMatrixArray< number >::Tvmult ( BlockVector< number > &  dst,
const BlockVector< number > &  src 
) const

Transposed matrix-vector multiplication.

Reimplemented in BlockTrianglePrecondition< number >.

template<typename number = double>
void BlockMatrixArray< number >::Tvmult_add ( BlockVector< number > &  dst,
const BlockVector< number > &  src 
) const

Transposed matrix-vector multiplication adding to dst.

Reimplemented in BlockTrianglePrecondition< number >.

template<typename number = double>
number BlockMatrixArray< number >::matrix_scalar_product ( const BlockVector< number > &  u,
const BlockVector< number > &  v 
) const

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

template<typename number = double>
number BlockMatrixArray< number >::matrix_norm_square ( const BlockVector< number > &  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.

template<typename number = double>
template<class STREAM >
void BlockMatrixArray< number >::print_latex ( STREAM &  out  )  const [inline]

Print the block structure as a LaTeX-array. This output will not be very intuitive, since the matrix object lacks important information. What you see is an entry for each block showing all the matrices with their multiplicaton factors and possibly transpose mark. The matrices itself are numbered successively upon being entred. If the same matrix is entered several times, it will be listed with the same number everytime.


Member Data Documentation

template<typename number = double>
std::vector<Entry> BlockMatrixArray< number >::entries [protected]

Array of block entries in the matrix.

template<typename number = double>
unsigned int BlockMatrixArray< number >::block_rows [private]

Number of blocks per column.

template<typename number = double>
unsigned int BlockMatrixArray< number >::block_cols [private]

number of blocks per row.

template<typename number = double>
SmartPointer<VectorMemory<Vector<number> > > BlockMatrixArray< number >::mem [mutable, protected]

The memory used for auxiliary vectors.


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

deal.II documentation generated on Mon Nov 23 22:57:29 2009 by doxygen 1.6.1