Reference documentation for deal.II version Git d4ec8156ca 2019-11-18 14:03:00 -0700
\(\newcommand{\dealcoloneq}{\mathrel{\vcenter{:}}=}\)
Public Types | Public Member Functions | Static Public Member Functions | Public Attributes | Private Attributes | List of all members

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

Inheritance diagram for MatrixBlock< MatrixType >:
[legend]

Public Types

using size_type = types::global_dof_index
 
using value_type = typename MatrixType::value_type
 

Public Member Functions

 MatrixBlock ()
 
 MatrixBlock (const MatrixBlock< MatrixType > &M)
 
 MatrixBlock (size_type i, size_type j)
 
void reinit (const BlockSparsityPattern &sparsity)
 
void add (const size_type i, const size_type j, const typename MatrixType::value_type value)
 
template<typename number >
void add (const std::vector< size_type > &indices, const FullMatrix< number > &full_matrix, const bool elide_zero_values=true)
 
template<typename number >
void add (const std::vector< size_type > &row_indices, const std::vector< size_type > &col_indices, const FullMatrix< number > &full_matrix, const bool elide_zero_values=true)
 
template<typename number >
void add (const size_type row_index, const std::vector< size_type > &col_indices, const std::vector< number > &values, const bool elide_zero_values=true)
 
template<typename number >
void add (const size_type row, const size_type n_cols, const size_type *col_indices, const number *values, const bool elide_zero_values=true, const bool col_indices_are_sorted=false)
 
template<class VectorType >
void vmult (VectorType &w, const VectorType &v) const
 
template<class VectorType >
void vmult_add (VectorType &w, const VectorType &v) const
 
template<class VectorType >
void Tvmult (VectorType &w, const VectorType &v) const
 
template<class VectorType >
void Tvmult_add (VectorType &w, const VectorType &v) const
 
std::size_t memory_consumption () const
 
- Public Member Functions inherited from Subscriptor
 Subscriptor ()
 
 Subscriptor (const Subscriptor &)
 
 Subscriptor (Subscriptor &&) noexcept
 
virtual ~Subscriptor ()
 
Subscriptoroperator= (const Subscriptor &)
 
Subscriptoroperator= (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)
 

Static Public Member Functions

static ::ExceptionBaseExcBlockIndexMismatch (size_type arg1, size_type arg2)
 
- Static Public Member Functions inherited from Subscriptor
static ::ExceptionBaseExcInUse (int arg1, std::string arg2, std::string arg3)
 
static ::ExceptionBaseExcNoSubscriber (std::string arg1, std::string arg2)
 

Public Attributes

size_type row
 
size_type column
 
MatrixType matrix
 

Private Attributes

BlockIndices row_indices
 
BlockIndices column_indices
 

Detailed Description

template<typename MatrixType>
class MatrixBlock< MatrixType >

A wrapper around a matrix object, storing the coordinates in a block matrix as well.

This class is an alternative to BlockMatrixBase, if you only want to generate a single block of the system, not the whole system. Using the add() functions of this class, it is possible to use the standard assembling functions used for block matrices, but only enter in one of the blocks and still avoiding the index computations involved. The reason for this class is, that we may need a different number of matrices for different blocks in a block system. For example, a preconditioner for the Oseen system can be built as a block system, where the pressure block is of the form M-1FA-1 with M the pressure mass matrix, A the pressure Laplacian and F the advection diffusion operator applied to the pressure space. Since only a single matrix is needed for the other blocks, using BlockSparseMatrix or similar would be a waste of memory.

While the add() functions make a MatrixBlock appear like a block matrix for assembling, the functions vmult(), Tvmult(), vmult_add(), and Tvmult_add() make it behave like a MatrixType, when it comes to applying it to a vector. This behavior allows us to store MatrixBlock objects in vectors, for instance in MGLevelObject without extracting the matrix first.

MatrixBlock comes handy when using BlockMatrixArray. Once the MatrixBlock has been properly initialized and filled, it can be used in the simplest case as:

...
BlockMatrixArray matrix (n_blocks, n_blocks);
for (size_type i=0;i<blocks.size;++i)
matrix.enter(blocks.block(i).row, blocks.block(i).column,
blocks.matrix(i));

Here, we have not gained very much, except that we do not need to set up empty blocks in the block system.

Note
This class expects, that the row and column BlockIndices objects for the system are equal. If they are not, some functions will throw ExcNotImplemented.
Todo:
Example for the product preconditioner of the pressure Schur complement.
See also
Block (linear algebra)
Author
Guido Kanschat, 2006

Definition at line 112 of file matrix_block.h.

Member Typedef Documentation

◆ size_type

template<typename MatrixType>
using MatrixBlock< MatrixType >::size_type = types::global_dof_index

Declare type for container size.

Definition at line 118 of file matrix_block.h.

◆ value_type

template<typename MatrixType>
using MatrixBlock< MatrixType >::value_type = typename MatrixType::value_type

Declare a type for matrix entries.

Definition at line 123 of file matrix_block.h.

Constructor & Destructor Documentation

◆ MatrixBlock() [1/3]

template<typename MatrixType >
MatrixBlock< MatrixType >::MatrixBlock ( )
inline

Constructor rendering an uninitialized object.

Definition at line 635 of file matrix_block.h.

◆ MatrixBlock() [2/3]

template<typename MatrixType>
MatrixBlock< MatrixType >::MatrixBlock ( const MatrixBlock< MatrixType > &  M)
inline

Copy constructor.

Definition at line 642 of file matrix_block.h.

◆ MatrixBlock() [3/3]

template<typename MatrixType>
MatrixBlock< MatrixType >::MatrixBlock ( size_type  i,
size_type  j 
)
inline

Constructor setting block coordinates, but not initializing the matrix.

Definition at line 653 of file matrix_block.h.

Member Function Documentation

◆ reinit()

template<typename MatrixType >
void MatrixBlock< MatrixType >::reinit ( const BlockSparsityPattern sparsity)
inline

Reinitialize the matrix for a new BlockSparsityPattern. This adjusts the matrix as well as the row_indices and column_indices.

Note
The row and column block structure of the sparsity pattern must be equal.

Definition at line 661 of file matrix_block.h.

◆ add() [1/5]

template<typename MatrixType>
void MatrixBlock< MatrixType >::add ( const size_type  i,
const size_type  j,
const typename MatrixType::value_type  value 
)
inline

Add value to the element (i,j). Throws an error if the entry does not exist or if it is in a different block.

Definition at line 683 of file matrix_block.h.

◆ add() [2/5]

template<typename MatrixType >
template<typename number >
void MatrixBlock< MatrixType >::add ( const std::vector< size_type > &  indices,
const FullMatrix< number > &  full_matrix,
const bool  elide_zero_values = true 
)
inline

Add all elements in a FullMatrix into sparse matrix locations given by indices. This function assumes a quadratic sparse matrix and a quadratic full_matrix. The global locations are translated into locations in this block and ExcBlockIndexMismatch is thrown, if the global index does not point into the block referred to by row and column.

Todo:
elide_zero_values is currently ignored.

The optional parameter elide_zero_values can be used to specify whether zero values should be added anyway or these should be filtered away and only non-zero data is added. The default value is true, i.e., zero values won't be added into the matrix.

Definition at line 766 of file matrix_block.h.

◆ add() [3/5]

template<typename MatrixType >
template<typename number >
void MatrixBlock< MatrixType >::add ( const std::vector< size_type > &  row_indices,
const std::vector< size_type > &  col_indices,
const FullMatrix< number > &  full_matrix,
const bool  elide_zero_values = true 
)
inline

Add all elements in a FullMatrix into global locations given by row_indices and col_indices, respectively. The global locations are translated into locations in this block and ExcBlockIndexMismatch is thrown, if the global index does not point into the block referred to by row and column.

Todo:
elide_zero_values is currently ignored.

The optional parameter elide_zero_values can be used to specify whether zero values should be added anyway or these should be filtered away and only non-zero data is added. The default value is true, i.e., zero values won't be added into the matrix.

Definition at line 704 of file matrix_block.h.

◆ add() [4/5]

template<typename MatrixType >
template<typename number >
void MatrixBlock< MatrixType >::add ( const size_type  row_index,
const std::vector< size_type > &  col_indices,
const std::vector< number > &  values,
const bool  elide_zero_values = true 
)
inline

Set several elements in the specified row of the matrix with column indices as given by col_indices to the respective value. This is the function doing the actual work for the ones adding full matrices. The global locations row_index and col_indices are translated into locations in this block and ExcBlockIndexMismatch is thrown, if the global index does not point into the block referred to by row and column.

Todo:
elide_zero_values is currently ignored.

The optional parameter elide_zero_values can be used to specify whether zero values should be added anyway or these should be filtered away and only non-zero data is added. The default value is true, i.e., zero values won't be added into the matrix.

Definition at line 789 of file matrix_block.h.

◆ add() [5/5]

template<typename MatrixType >
template<typename number >
void MatrixBlock< MatrixType >::add ( const size_type  row,
const size_type  n_cols,
const size_type col_indices,
const number *  values,
const bool  elide_zero_values = true,
const bool  col_indices_are_sorted = false 
)
inline

Add an array of values given by values in the given global matrix row at columns specified by col_indices in the sparse matrix.

The optional parameter elide_zero_values can be used to specify whether zero values should be added anyway or these should be filtered away and only non-zero data is added. The default value is true, i.e., zero values won't be added into the matrix.

Definition at line 727 of file matrix_block.h.

◆ vmult()

template<typename MatrixType >
template<class VectorType >
void MatrixBlock< MatrixType >::vmult ( VectorType &  w,
const VectorType &  v 
) const
inline

Matrix-vector-multiplication, forwarding to the same function in MatrixType. No index computations are done, thus, the vectors need to have sizes matching matrix.

Definition at line 809 of file matrix_block.h.

◆ vmult_add()

template<typename MatrixType >
template<class VectorType >
void MatrixBlock< MatrixType >::vmult_add ( VectorType &  w,
const VectorType &  v 
) const
inline

Matrix-vector-multiplication, forwarding to the same function in MatrixType. No index computations are done, thus, the vectors need to have sizes matching matrix.

Definition at line 818 of file matrix_block.h.

◆ Tvmult()

template<typename MatrixType >
template<class VectorType >
void MatrixBlock< MatrixType >::Tvmult ( VectorType &  w,
const VectorType &  v 
) const
inline

Matrix-vector-multiplication, forwarding to the same function in MatrixType. No index computations are done, thus, the vectors need to have sizes matching matrix.

Definition at line 827 of file matrix_block.h.

◆ Tvmult_add()

template<typename MatrixType >
template<class VectorType >
void MatrixBlock< MatrixType >::Tvmult_add ( VectorType &  w,
const VectorType &  v 
) const
inline

Matrix-vector-multiplication, forwarding to the same function in MatrixType. No index computations are done, thus, the vectors need to have sizes matching matrix.

Definition at line 836 of file matrix_block.h.

◆ memory_consumption()

template<typename MatrixType >
std::size_t MatrixBlock< MatrixType >::memory_consumption ( ) const
inline

The memory used by this object.

Definition at line 844 of file matrix_block.h.

Member Data Documentation

◆ row

template<typename MatrixType>
size_type MatrixBlock< MatrixType >::row

Row coordinate. This is the position of the data member matrix on the global matrix.

Definition at line 301 of file matrix_block.h.

◆ column

template<typename MatrixType>
size_type MatrixBlock< MatrixType >::column

Column coordinate. This is the position of the data member matrix on the global matrix.

Definition at line 306 of file matrix_block.h.

◆ matrix

template<typename MatrixType>
MatrixType MatrixBlock< MatrixType >::matrix

The matrix itself

Definition at line 311 of file matrix_block.h.

◆ row_indices

template<typename MatrixType>
BlockIndices MatrixBlock< MatrixType >::row_indices
private

The row BlockIndices of the whole system. Using row(), this allows us to find the index of the first row degree of freedom for this block.

Definition at line 318 of file matrix_block.h.

◆ column_indices

template<typename MatrixType>
BlockIndices MatrixBlock< MatrixType >::column_indices
private

The column BlockIndices of the whole system. Using column(), this allows us to find the index of the first column degree of freedom for this block.

Definition at line 324 of file matrix_block.h.


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