dune-istl 2.9.0
Classes | Public Types | Public Member Functions | Static Public Attributes | Protected Types | Protected Member Functions | Protected Attributes | List of all members
Dune::BCRSMatrix< B, A > Class Template Reference

A sparse block matrix with compressed row storage. More...

#include <dune/istl/bcrsmatrix.hh>

Inheritance diagram for Dune::BCRSMatrix< B, A >:
Inheritance graph

Classes

class  CreateIterator
 Iterator class for sequential creation of blocks More...
 
class  RealRowIterator
 Iterator access to matrix rows More...
 

Public Types

enum  BuildStage {
  notbuilt =0 , notAllocated =0 , building =1 , rowSizesBuilt =2 ,
  built =3
}
 
enum  BuildMode { row_wise , random , implicit , unknown }
 we support two modes More...
 
using field_type = typename Imp::BlockTraits< B >::field_type
 export the type representing the field More...
 
typedef B block_type
 export the type representing the components More...
 
typedef A allocator_type
 export the allocator type More...
 
typedef Imp::CompressedBlockVectorWindow< B, A > row_type
 implement row_type with compressed vector More...
 
typedef A::size_type size_type
 The type for the index access and the size. More...
 
typedef ::Dune::CompressionStatistics< size_typeCompressionStatistics
 The type for the statistics object returned by compress() More...
 
typedef RealRowIterator< row_typeiterator
 The iterator over the (mutable matrix rows. More...
 
typedef RealRowIterator< row_typeIterator
 
typedef Iterator RowIterator
 rename the iterators for easier access More...
 
typedef row_type::Iterator ColIterator
 Iterator for the entries of each row. More...
 
typedef RealRowIterator< const row_typeconst_iterator
 The const iterator over the matrix rows. More...
 
typedef RealRowIterator< const row_typeConstIterator
 
typedef ConstIterator ConstRowIterator
 rename the const row iterator for easier access More...
 
typedef row_type::ConstIterator ConstColIterator
 Const iterator to the entries of a row. More...
 

Public Member Functions

row_typeoperator[] (size_type i)
 random access to the rows More...
 
const row_typeoperator[] (size_type i) const
 same for read only access More...
 
Iterator begin ()
 Get iterator to first row. More...
 
Iterator end ()
 Get iterator to one beyond last row. More...
 
Iterator beforeEnd ()
 
Iterator beforeBegin ()
 
ConstIterator begin () const
 Get const iterator to first row. More...
 
ConstIterator end () const
 Get const iterator to one beyond last row. More...
 
ConstIterator beforeEnd () const
 
ConstIterator beforeBegin () const
 
 BCRSMatrix ()
 an empty matrix More...
 
 BCRSMatrix (size_type _n, size_type _m, size_type _nnz, BuildMode bm)
 matrix with known number of nonzeroes More...
 
 BCRSMatrix (size_type _n, size_type _m, BuildMode bm)
 matrix with unknown number of nonzeroes More...
 
 BCRSMatrix (size_type _n, size_type _m, size_type _avg, double compressionBufferSize, BuildMode bm)
 construct matrix with a known average number of entries per row More...
 
 BCRSMatrix (const BCRSMatrix &Mat)
 copy constructor More...
 
 ~BCRSMatrix ()
 destructor More...
 
void setBuildMode (BuildMode bm)
 Sets the build mode of the matrix. More...
 
void setSize (size_type rows, size_type columns, size_type nnz=0)
 Set the size of the matrix. More...
 
void setImplicitBuildModeParameters (size_type _avg, double compressionBufferSize)
 Set parameters needed for creation in implicit build mode. More...
 
BCRSMatrixoperator= (const BCRSMatrix &Mat)
 assignment More...
 
BCRSMatrixoperator= (const field_type &k)
 Assignment from a scalar. More...
 
CreateIterator createbegin ()
 get initial create iterator More...
 
CreateIterator createend ()
 get create iterator pointing to one after the last block More...
 
void setrowsize (size_type i, size_type s)
 Set number of indices in row i to s. More...
 
size_type getrowsize (size_type i) const
 get current number of indices in row i More...
 
void incrementrowsize (size_type i, size_type s=1)
 increment size of row i by s (1 by default) More...
 
void endrowsizes ()
 indicate that size of all rows is defined More...
 
void addindex (size_type row, size_type col)
 add index (row,col) to the matrix More...
 
template<typename It >
void setIndices (size_type row, It begin, It end)
 Set all column indices for row from the given iterator range. More...
 
void endindices ()
 indicate that all indices are defined, check consistency More...
 
B & entry (size_type row, size_type col)
 Returns reference to entry (row,col) of the matrix. More...
 
CompressionStatistics compress ()
 Finishes the buildstage in implicit mode. More...
 
BCRSMatrixoperator*= (const field_type &k)
 vector space multiplication with scalar More...
 
BCRSMatrixoperator/= (const field_type &k)
 vector space division by scalar More...
 
BCRSMatrixoperator+= (const BCRSMatrix &b)
 Add the entries of another matrix to this one. More...
 
BCRSMatrixoperator-= (const BCRSMatrix &b)
 Subtract the entries of another matrix from this one. More...
 
BCRSMatrixaxpy (field_type alpha, const BCRSMatrix &b)
 Add the scaled entries of another matrix to this one. More...
 
template<class X , class Y >
void mv (const X &x, Y &y) const
 y = A x More...
 
template<class X , class Y >
void umv (const X &x, Y &y) const
 y += A x More...
 
template<class X , class Y >
void mmv (const X &x, Y &y) const
 y -= A x More...
 
template<class X , class Y , class F >
void usmv (F &&alpha, const X &x, Y &y) const
 y += alpha A x More...
 
template<class X , class Y >
void mtv (const X &x, Y &y) const
 y = A^T x More...
 
template<class X , class Y >
void umtv (const X &x, Y &y) const
 y += A^T x More...
 
template<class X , class Y >
void mmtv (const X &x, Y &y) const
 y -= A^T x More...
 
template<class X , class Y >
void usmtv (const field_type &alpha, const X &x, Y &y) const
 y += alpha A^T x More...
 
template<class X , class Y >
void umhv (const X &x, Y &y) const
 y += A^H x More...
 
template<class X , class Y >
void mmhv (const X &x, Y &y) const
 y -= A^H x More...
 
template<class X , class Y >
void usmhv (const field_type &alpha, const X &x, Y &y) const
 y += alpha A^H x More...
 
FieldTraits< field_type >::real_type frobenius_norm2 () const
 square of frobenius norm, need for block recursion More...
 
FieldTraits< field_type >::real_type frobenius_norm () const
 frobenius norm: sqrt(sum over squared values of entries) More...
 
template<typename ft = field_type, typename std::enable_if<!HasNaN< ft >::value, int >::type = 0>
FieldTraits< ft >::real_type infinity_norm () const
 infinity norm (row sum norm, how to generalize for blocks?) More...
 
template<typename ft = field_type, typename std::enable_if<!HasNaN< ft >::value, int >::type = 0>
FieldTraits< ft >::real_type infinity_norm_real () const
 simplified infinity norm (uses Manhattan norm for complex values) More...
 
template<typename ft = field_type, typename std::enable_if< HasNaN< ft >::value, int >::type = 0>
FieldTraits< ft >::real_type infinity_norm () const
 infinity norm (row sum norm, how to generalize for blocks?) More...
 
template<typename ft = field_type, typename std::enable_if< HasNaN< ft >::value, int >::type = 0>
FieldTraits< ft >::real_type infinity_norm_real () const
 simplified infinity norm (uses Manhattan norm for complex values) More...
 
size_type N () const
 number of rows (counted in blocks) More...
 
size_type M () const
 number of columns (counted in blocks) More...
 
size_type nonzeroes () const
 number of blocks that are stored (the number of blocks that possibly are nonzero) More...
 
BuildStage buildStage () const
 The current build stage of the matrix. More...
 
BuildMode buildMode () const
 The currently selected build mode of the matrix. More...
 
bool exists (size_type i, size_type j) const
 return true if (i,j) is in pattern More...
 

Static Public Attributes

static constexpr unsigned int blocklevel = blockLevel<B>()+1
 increment block level counter More...
 

Protected Types

typedef std::map< std::pair< size_type, size_type >, B > OverflowType
 

Protected Member Functions

void setWindowPointers (ConstRowIterator row)
 
void setColumnPointers (ConstRowIterator row)
 Copy row sizes from iterator range starting at row and set column index pointers for all rows. More...
 
void setDataPointers ()
 Set data pointers for all rows. More...
 
void copyWindowStructure (const BCRSMatrix &Mat)
 Copy the window structure from another matrix. More...
 
void deallocate (bool deallocateRows=true)
 deallocate memory of the matrix. More...
 
void allocate (size_type rows, size_type columns, size_type allocationSize, bool allocateRows, bool allocate_data)
 Allocate memory for the matrix structure. More...
 
void allocateData ()
 
void implicit_allocate (size_type _n, size_type _m)
 organizes allocation implicit mode calculates correct array size to be allocated and sets the the window pointers to their correct positions for insertion. internally uses allocate() for the real allocation. More...
 

Protected Attributes

BuildMode build_mode
 
BuildStage ready
 
std::allocator_traits< A >::template rebind_alloc< B > allocator_
 
std::allocator_traits< A >::template rebind_alloc< row_typerowAllocator_
 
std::allocator_traits< A >::template rebind_alloc< size_typesizeAllocator_
 
size_type n
 
size_type m
 
size_type nnz_
 
size_type allocationSize_
 
row_typer
 
B * a
 
std::shared_ptr< size_typej_
 
size_type avg
 
double compressionBufferSize_
 
OverflowType overflow
 

Detailed Description

template<class B, class A = std::allocator<B>>
class Dune::BCRSMatrix< B, A >

A sparse block matrix with compressed row storage.

Implements a block compressed row storage scheme. The block type B can be any type implementing the matrix interface.

Different ways to build up a compressed row storage matrix are supported:

  1. Row-wise scheme
  2. Random scheme
  3. implicit scheme

Error checking: no error checking is provided normally. Setting the compile time switch DUNE_ISTL_WITH_CHECKING enables error checking.

Details:

  1. Row-wise scheme

Rows are built up in sequential order. Size of the row and the column indices are defined. A row can be used as soon as it is initialized. With respect to memory there are two variants of this scheme: (a) number of non-zeroes known in advance (application finite difference schemes), (b) number of non-zeroes not known in advance (application: Sparse LU, ILU(n)).

#include<dune/common/fmatrix.hh>
...
// third parameter is an optional upper bound for the number
// of nonzeros. If given the matrix will use one array for all values
// as opposed to one for each row.
for(Iter row=B.createbegin(); row!=B.createend(); ++row){
// Add nonzeros for left neighbour, diagonal and right neighbour
if(row.index()>0)
row.insert(row.index()-1);
row.insert(row.index());
if(row.index()<B.N()-1)
row.insert(row.index()+1);
}
// Now the sparsity pattern is fully set up and we can add values
B[0][0]=2;
...
Implementation of the BCRSMatrix class.
A sparse block matrix with compressed row storage.
Definition: bcrsmatrix.hh:466
size_type M() const
number of columns (counted in blocks)
Definition: bcrsmatrix.hh:1978
Iterator class for sequential creation of blocks
Definition: bcrsmatrix.hh:957
Definition: matrixutils.hh:27
  1. Random scheme

For general finite element implementations the number of rows n is known, the number of non-zeroes might also be known (e.g. #edges + #nodes for P2) but the size of a row and the indices of a row can not be defined in sequential order.

#include<dune/common/fmatrix.hh>
...
// initially set row size for each row
B.setrowsize(0,1);
B.setrowsize(3,4);
B.setrowsize(2,1);
B.setrowsize(1,1);
// increase row size for row 2
B.incrementrowsize(2);
// finalize row setup phase
B.endrowsizes();
// add column entries to rows
B.addindex(0,0);
B.addindex(3,1);
B.addindex(2,2);
B.addindex(1,1);
B.addindex(2,0);
B.addindex(3,2);
B.addindex(3,0);
B.addindex(3,3);
// finalize column setup phase
B.endindices();
// set entries using the random access operator
B[0][0] = 1;
B[1][1] = 2;
B[2][0] = 3;
B[2][2] = 4;
B[3][1] = 5;
B[3][2] = 6;
B[3][0] = 7;
B[3][3] = 8;
  1. implicit scheme

With the 'random scheme` described above, the sparsity pattern has to be determined and stored before the matrix is assembled. This requires a dedicated iteration over the grid elements, which can be costly in terms of time. Also, additional memory is needed to store the pattern before it can be given to the 'random' build mode.

On the other hand, often one has good a priori knowledge about the number of entries a row contains on average. The implicit mode tries to make use of that knowledge, and allows the setup of matrix pattern and numerical values together.

Constructing and filling a BCRSMatrix with the 'implicit' mode is performed in two steps: In a setup phase, matrix entries with numerical values can be inserted into the matrix. Then, a compression algorithm is called which defragments and optimizes the memory layout. After this compression step, the matrix is ready to be used, and no further nonzero entries can be added.

To use this mode, either construct a matrix object via

or default-construct the matrix and then call

The parameter _avg specifies the expected number of (block) entries per matrix row.

When the BCRSMatrix object is first constructed with the 'implicit' build mode, two areas for matrix entry storage are allocated:

1) A large continuous chunk of memory that can hold the expected number of entries. In addition, this chunk contains an extra part of memory called the 'compression buffer', located before the memory for the matrix itself. The size of this buffer will be _avg * _n * compressionBufferSize.

2) An associative container indexed by $i,j$-pairs, which will hold surplus matrix entries during the setup phase (the 'overflow area'). Its content is merged into the main memory during compression.

You can then start filling your matrix by calling entry(size_type row, size_type col), which returns the corresponding matrix entry, creating it on the fly if it does not exist yet. The matrix pattern is hence created implicitly by simply accessing nonzero entries during the initial matrix assembly. Note that new entries are not zero-initialized, though, and hence the first operation on each entry has to be an assignment.

If a row contains more non-zero entries than what was specified in the _avg parameter, the surplus entries are stored in the 'overflow area' during the initial setup phase. After all indices are added, call compress() to trigger the compression step that optimizes the matrix and integrates any entries from the overflow area into the standard BCRS storage. This compression step builds up the final memory layout row by row. It will fail with an exception if the compression buffer is not large enough, which would lead to compressed rows overwriting uncompressed ones. More precisely, if $\textrm{nnz}_j$ denotes the number of non-zeros in the $j$-th row, then the compression algorithm will succeed if the maximal number of non-zeros in the $i$-th row is

\[
   M_i = \textrm{avg} + A + \sum_{j<i} (\textrm{avg} - \textrm{nnz}_j)
\]

for all $i$, where $ A = \textrm{avg}(n \cdot \textrm{compressionBufferSize}) $ is the total size of the compression buffer determined by the parameters explained above.

The data of the matrix is now located at the beginning of the allocated area, and covers what used to be the compression buffer. In exchange, there is now unused space at the end of the large allocated piece of memory. This will go unused and cannot be freed during the lifetime of the matrix, but it has no negative impact on run-time performance. No matrix entries may be added after the compression step.

The compress() method returns a value of type Dune::CompressionStatistics, which you can inspect to tune the construction parameters _avg and compressionBufferSize.

Use of copy constructor, assignment operator and matrix vector arithmetics are not supported until the matrix is fully built.

The following sample code constructs a $ 10 \times 10$ matrix, with an expected number of two entries per matrix row. The compression buffer size is set to 0.4. Hence the main chunk of allocated memory will be able to hold 10 * 2 entries in the matrix rows, and 10 * 2 * 0.4 entries in the compression buffer. In total that's 28 entries.

M m(10, 10, 2, 0.4, M::implicit);
// Fill in some arbitrary entries; the order is irrelevant.
// Even operations on these would be possible, you get a reference to the entry!
m.entry(0,0) = 0.;
m.entry(8,0) = 0.;
m.entry(1,8) = 0.; m.entry(1,0) = 0.; m.entry(1,5) = 0.;
m.entry(2,0) = 0.;
m.entry(3,5) = 0.; m.entry(3,0) = 0.; m.entry(3,8) = 0.;
m.entry(4,0) = 0.;
m.entry(9,0) = 0.; m.entry(9,5) = 0.; m.entry(9,8) = 0.;
m.entry(5,0) = 0.; m.entry(5,5) = 0.; m.entry(5,8) = 0.;
m.entry(6,0) = 0.;
m.entry(7,0) = 0.; m.entry(7,5) = 0.; m.entry(7,8) = 0.;
size_type m
Definition: bcrsmatrix.hh:2031

Internally the index array now looks like this:

// xxxxxxxx0x800x500x050x050x05
// ........|.|.|.|.|.|.|.|.|.|.

The second row denotes the beginnings of the matrix rows. The eight 'x' on the left are the compression buffer. The overflow area contains the entries (1,5,0.0), (3,8,0.0), (5,8,0.0), (7,8,0.0), and (9,8,0.0). These are entries of rows 1, 3, 5, 7, and 9, which have three entries each, even though only two were anticipated.

//finish building by compressing the array
Statistics about compression achieved in implicit mode.
Definition: bcrsmatrix.hh:88

Internally the index array now looks like this:

// 00580058005800580058xxxxxxxx
// ||..||..||..||..||..........

The compression buffer on the left is gone now, and the matrix has a real CRS layout. The 'x' on the right will be unused for the rest of the matrix' lifetime.

Member Typedef Documentation

◆ allocator_type

template<class B , class A = std::allocator<B>>
typedef A Dune::BCRSMatrix< B, A >::allocator_type

export the allocator type

◆ block_type

template<class B , class A = std::allocator<B>>
typedef B Dune::BCRSMatrix< B, A >::block_type

export the type representing the components

◆ ColIterator

template<class B , class A = std::allocator<B>>
typedef row_type::Iterator Dune::BCRSMatrix< B, A >::ColIterator

Iterator for the entries of each row.

◆ CompressionStatistics

template<class B , class A = std::allocator<B>>
typedef ::Dune::CompressionStatistics<size_type> Dune::BCRSMatrix< B, A >::CompressionStatistics

The type for the statistics object returned by compress()

◆ const_iterator

template<class B , class A = std::allocator<B>>
typedef RealRowIterator<const row_type> Dune::BCRSMatrix< B, A >::const_iterator

The const iterator over the matrix rows.

◆ ConstColIterator

template<class B , class A = std::allocator<B>>
typedef row_type::ConstIterator Dune::BCRSMatrix< B, A >::ConstColIterator

Const iterator to the entries of a row.

◆ ConstIterator

template<class B , class A = std::allocator<B>>
typedef RealRowIterator<const row_type> Dune::BCRSMatrix< B, A >::ConstIterator

◆ ConstRowIterator

template<class B , class A = std::allocator<B>>
typedef ConstIterator Dune::BCRSMatrix< B, A >::ConstRowIterator

rename the const row iterator for easier access

◆ field_type

template<class B , class A = std::allocator<B>>
using Dune::BCRSMatrix< B, A >::field_type = typename Imp::BlockTraits<B>::field_type

export the type representing the field

◆ iterator

template<class B , class A = std::allocator<B>>
typedef RealRowIterator<row_type> Dune::BCRSMatrix< B, A >::iterator

The iterator over the (mutable matrix rows.

◆ Iterator

template<class B , class A = std::allocator<B>>
typedef RealRowIterator<row_type> Dune::BCRSMatrix< B, A >::Iterator

◆ OverflowType

template<class B , class A = std::allocator<B>>
typedef std::map<std::pair<size_type,size_type>, B> Dune::BCRSMatrix< B, A >::OverflowType
protected

◆ row_type

template<class B , class A = std::allocator<B>>
typedef Imp::CompressedBlockVectorWindow<B,A> Dune::BCRSMatrix< B, A >::row_type

implement row_type with compressed vector

◆ RowIterator

template<class B , class A = std::allocator<B>>
typedef Iterator Dune::BCRSMatrix< B, A >::RowIterator

rename the iterators for easier access

◆ size_type

template<class B , class A = std::allocator<B>>
typedef A::size_type Dune::BCRSMatrix< B, A >::size_type

The type for the index access and the size.

Member Enumeration Documentation

◆ BuildMode

template<class B , class A = std::allocator<B>>
enum Dune::BCRSMatrix::BuildMode

we support two modes

Enumerator
row_wise 

Build in a row-wise manner.

Rows are built up in sequential order. Size of the row and the column indices are defined. A row can be used as soon as it is initialized. With respect to memory there are two variants of this scheme: (a) number of non-zeroes known in advance (application finite difference schemes), (b) number of non-zeroes not known in advance (application: Sparse LU, ILU(n)).

random 

Build entries randomly.

For general finite element implementations the number of rows n is known, the number of non-zeroes might also be known (e.g. #edges + #nodes for P2) but the size of a row and the indices of a row cannot be defined in sequential order.

implicit 

Build entries randomly with an educated guess for the number of entries per row.

Allows random order generation as in random mode, but row sizes do not need to be given first. Instead an average number of non-zeroes per row is passed to the constructor. Matrix setup is finished with compress(), full data access during build stage is possible.

unknown 

Build mode not set!

◆ BuildStage

template<class B , class A = std::allocator<B>>
enum Dune::BCRSMatrix::BuildStage
Enumerator
notbuilt 

Matrix is not built at all, no memory has been allocated, build mode and size can still be set.

notAllocated 

Matrix is not built at all, no memory has been allocated, build mode and size can still be set.

building 

Matrix is currently being built, some memory has been allocated, build mode and size are fixed.

rowSizesBuilt 

The row sizes of the matrix are known.

 Only used in random mode.
built 

The matrix structure is fully built.

Constructor & Destructor Documentation

◆ BCRSMatrix() [1/5]

template<class B , class A = std::allocator<B>>
Dune::BCRSMatrix< B, A >::BCRSMatrix ( )
inline

an empty matrix

◆ BCRSMatrix() [2/5]

template<class B , class A = std::allocator<B>>
Dune::BCRSMatrix< B, A >::BCRSMatrix ( size_type  _n,
size_type  _m,
size_type  _nnz,
BuildMode  bm 
)
inline

matrix with known number of nonzeroes

◆ BCRSMatrix() [3/5]

template<class B , class A = std::allocator<B>>
Dune::BCRSMatrix< B, A >::BCRSMatrix ( size_type  _n,
size_type  _m,
BuildMode  bm 
)
inline

matrix with unknown number of nonzeroes

◆ BCRSMatrix() [4/5]

template<class B , class A = std::allocator<B>>
Dune::BCRSMatrix< B, A >::BCRSMatrix ( size_type  _n,
size_type  _m,
size_type  _avg,
double  compressionBufferSize,
BuildMode  bm 
)
inline

construct matrix with a known average number of entries per row

Constructs a matrix in implicit buildmode.

Parameters
_nnumber of rows of the matrix
_mnumber of columns of the matrix
_avgexpected average number of entries per row
compressionBufferSizefraction of _n*_avg which is expected to be needed for elements that exceed _avg entries per row.

◆ BCRSMatrix() [5/5]

template<class B , class A = std::allocator<B>>
Dune::BCRSMatrix< B, A >::BCRSMatrix ( const BCRSMatrix< B, A > &  Mat)
inline

copy constructor

Does a deep copy as expected.

◆ ~BCRSMatrix()

template<class B , class A = std::allocator<B>>
Dune::BCRSMatrix< B, A >::~BCRSMatrix ( )
inline

destructor

Member Function Documentation

◆ addindex()

template<class B , class A = std::allocator<B>>
void Dune::BCRSMatrix< B, A >::addindex ( size_type  row,
size_type  col 
)
inline

add index (row,col) to the matrix

This method can only be used when building the BCRSMatrix in random mode.

addindex adds a new column entry to the row. If this column entry already exists, nothing is done.

Don't call addindex after the setup phase is finished (after endindices is called).

◆ allocate()

template<class B , class A = std::allocator<B>>
void Dune::BCRSMatrix< B, A >::allocate ( size_type  rows,
size_type  columns,
size_type  allocationSize,
bool  allocateRows,
bool  allocate_data 
)
inlineprotected

Allocate memory for the matrix structure.

Sets the number of rows and columns of the matrix and allocates the memory needed for the storage of the matrix entries.

Warning
After calling this methods on an already allocated (and probably setup matrix) results in all the structure and data being lost. Please call deallocate() before calling allocate in this case.
Parameters
rowThe number of rows the matrix should contain.
columnsthe number of columns the matrix should contain.
allocationSizeThe number of nonzero entries the matrix should hold (if omitted defaults to 0).
allocateRowWhether we have to allocate the row pointers, too. (Defaults to true)

◆ allocateData()

template<class B , class A = std::allocator<B>>
void Dune::BCRSMatrix< B, A >::allocateData ( )
inlineprotected

◆ axpy()

template<class B , class A = std::allocator<B>>
BCRSMatrix & Dune::BCRSMatrix< B, A >::axpy ( field_type  alpha,
const BCRSMatrix< B, A > &  b 
)
inline

Add the scaled entries of another matrix to this one.

Matrix axpy operation: *this += alpha * b

Parameters
alphaScaling factor.
bThe matrix to add to this one. Its sparsity pattern has to be subset of the sparsity pattern of this matrix.

◆ beforeBegin() [1/2]

template<class B , class A = std::allocator<B>>
Iterator Dune::BCRSMatrix< B, A >::beforeBegin ( )
inline
Returns
an iterator that is positioned before the first row of the matrix.

◆ beforeBegin() [2/2]

template<class B , class A = std::allocator<B>>
ConstIterator Dune::BCRSMatrix< B, A >::beforeBegin ( ) const
inline
Returns
an iterator that is positioned before the first row of the matrix.

◆ beforeEnd() [1/2]

template<class B , class A = std::allocator<B>>
Iterator Dune::BCRSMatrix< B, A >::beforeEnd ( )
inline
Returns
an iterator that is positioned before the end iterator of the rows, i.e. at the last row.

◆ beforeEnd() [2/2]

template<class B , class A = std::allocator<B>>
ConstIterator Dune::BCRSMatrix< B, A >::beforeEnd ( ) const
inline
Returns
an iterator that is positioned before the end iterator of the rows. i.e. at the last row.

◆ begin() [1/2]

template<class B , class A = std::allocator<B>>
Iterator Dune::BCRSMatrix< B, A >::begin ( )
inline

Get iterator to first row.

◆ begin() [2/2]

template<class B , class A = std::allocator<B>>
ConstIterator Dune::BCRSMatrix< B, A >::begin ( ) const
inline

Get const iterator to first row.

◆ buildMode()

template<class B , class A = std::allocator<B>>
BuildMode Dune::BCRSMatrix< B, A >::buildMode ( ) const
inline

The currently selected build mode of the matrix.

◆ buildStage()

template<class B , class A = std::allocator<B>>
BuildStage Dune::BCRSMatrix< B, A >::buildStage ( ) const
inline

The current build stage of the matrix.

◆ compress()

template<class B , class A = std::allocator<B>>
CompressionStatistics Dune::BCRSMatrix< B, A >::compress ( )
inline

Finishes the buildstage in implicit mode.

Performs compression of index and data arrays with linear complexity in the number of nonzeroes.

After calling this method, the matrix is in the built state and no more entries can be added.

Returns
An object with some statistics about the compression for future optimization.

◆ copyWindowStructure()

template<class B , class A = std::allocator<B>>
void Dune::BCRSMatrix< B, A >::copyWindowStructure ( const BCRSMatrix< B, A > &  Mat)
inlineprotected

Copy the window structure from another matrix.

◆ createbegin()

template<class B , class A = std::allocator<B>>
CreateIterator Dune::BCRSMatrix< B, A >::createbegin ( )
inline

get initial create iterator

◆ createend()

template<class B , class A = std::allocator<B>>
CreateIterator Dune::BCRSMatrix< B, A >::createend ( )
inline

get create iterator pointing to one after the last block

◆ deallocate()

template<class B , class A = std::allocator<B>>
void Dune::BCRSMatrix< B, A >::deallocate ( bool  deallocateRows = true)
inlineprotected

deallocate memory of the matrix.

Parameters
deallocateRowsWhether we have to deallocate the row pointers, too. If false they will not be touched. (Defaults to true).

◆ end() [1/2]

template<class B , class A = std::allocator<B>>
Iterator Dune::BCRSMatrix< B, A >::end ( )
inline

Get iterator to one beyond last row.

◆ end() [2/2]

template<class B , class A = std::allocator<B>>
ConstIterator Dune::BCRSMatrix< B, A >::end ( ) const
inline

Get const iterator to one beyond last row.

◆ endindices()

template<class B , class A = std::allocator<B>>
void Dune::BCRSMatrix< B, A >::endindices ( )
inline

indicate that all indices are defined, check consistency

◆ endrowsizes()

template<class B , class A = std::allocator<B>>
void Dune::BCRSMatrix< B, A >::endrowsizes ( )
inline

indicate that size of all rows is defined

◆ entry()

template<class B , class A = std::allocator<B>>
B & Dune::BCRSMatrix< B, A >::entry ( size_type  row,
size_type  col 
)
inline

Returns reference to entry (row,col) of the matrix.

This method can only be used when the matrix is in implicit building mode.

A reference to entry (row, col) of the matrix is returned. If entry (row, col) is accessed for the first time, it is created on the fly.

This method can only be used while building the matrix, after compression operator[] gives a much better performance.

◆ exists()

template<class B , class A = std::allocator<B>>
bool Dune::BCRSMatrix< B, A >::exists ( size_type  i,
size_type  j 
) const
inline

return true if (i,j) is in pattern

◆ frobenius_norm()

template<class B , class A = std::allocator<B>>
FieldTraits< field_type >::real_type Dune::BCRSMatrix< B, A >::frobenius_norm ( ) const
inline

frobenius norm: sqrt(sum over squared values of entries)

◆ frobenius_norm2()

template<class B , class A = std::allocator<B>>
FieldTraits< field_type >::real_type Dune::BCRSMatrix< B, A >::frobenius_norm2 ( ) const
inline

square of frobenius norm, need for block recursion

◆ getrowsize()

template<class B , class A = std::allocator<B>>
size_type Dune::BCRSMatrix< B, A >::getrowsize ( size_type  i) const
inline

get current number of indices in row i

◆ implicit_allocate()

template<class B , class A = std::allocator<B>>
void Dune::BCRSMatrix< B, A >::implicit_allocate ( size_type  _n,
size_type  _m 
)
inlineprotected

organizes allocation implicit mode calculates correct array size to be allocated and sets the the window pointers to their correct positions for insertion. internally uses allocate() for the real allocation.

◆ incrementrowsize()

template<class B , class A = std::allocator<B>>
void Dune::BCRSMatrix< B, A >::incrementrowsize ( size_type  i,
size_type  s = 1 
)
inline

increment size of row i by s (1 by default)

◆ infinity_norm() [1/2]

template<class B , class A = std::allocator<B>>
template<typename ft = field_type, typename std::enable_if<!HasNaN< ft >::value, int >::type = 0>
FieldTraits< ft >::real_type Dune::BCRSMatrix< B, A >::infinity_norm ( ) const
inline

infinity norm (row sum norm, how to generalize for blocks?)

◆ infinity_norm() [2/2]

template<class B , class A = std::allocator<B>>
template<typename ft = field_type, typename std::enable_if< HasNaN< ft >::value, int >::type = 0>
FieldTraits< ft >::real_type Dune::BCRSMatrix< B, A >::infinity_norm ( ) const
inline

infinity norm (row sum norm, how to generalize for blocks?)

◆ infinity_norm_real() [1/2]

template<class B , class A = std::allocator<B>>
template<typename ft = field_type, typename std::enable_if<!HasNaN< ft >::value, int >::type = 0>
FieldTraits< ft >::real_type Dune::BCRSMatrix< B, A >::infinity_norm_real ( ) const
inline

simplified infinity norm (uses Manhattan norm for complex values)

◆ infinity_norm_real() [2/2]

template<class B , class A = std::allocator<B>>
template<typename ft = field_type, typename std::enable_if< HasNaN< ft >::value, int >::type = 0>
FieldTraits< ft >::real_type Dune::BCRSMatrix< B, A >::infinity_norm_real ( ) const
inline

simplified infinity norm (uses Manhattan norm for complex values)

◆ M()

template<class B , class A = std::allocator<B>>
size_type Dune::BCRSMatrix< B, A >::M ( ) const
inline

number of columns (counted in blocks)

◆ mmhv()

template<class B , class A = std::allocator<B>>
template<class X , class Y >
void Dune::BCRSMatrix< B, A >::mmhv ( const X &  x,
Y &  y 
) const
inline

y -= A^H x

◆ mmtv()

template<class B , class A = std::allocator<B>>
template<class X , class Y >
void Dune::BCRSMatrix< B, A >::mmtv ( const X &  x,
Y &  y 
) const
inline

y -= A^T x

◆ mmv()

template<class B , class A = std::allocator<B>>
template<class X , class Y >
void Dune::BCRSMatrix< B, A >::mmv ( const X &  x,
Y &  y 
) const
inline

y -= A x

◆ mtv()

template<class B , class A = std::allocator<B>>
template<class X , class Y >
void Dune::BCRSMatrix< B, A >::mtv ( const X &  x,
Y &  y 
) const
inline

y = A^T x

◆ mv()

template<class B , class A = std::allocator<B>>
template<class X , class Y >
void Dune::BCRSMatrix< B, A >::mv ( const X &  x,
Y &  y 
) const
inline

y = A x

◆ N()

template<class B , class A = std::allocator<B>>
size_type Dune::BCRSMatrix< B, A >::N ( ) const
inline

number of rows (counted in blocks)

◆ nonzeroes()

template<class B , class A = std::allocator<B>>
size_type Dune::BCRSMatrix< B, A >::nonzeroes ( ) const
inline

number of blocks that are stored (the number of blocks that possibly are nonzero)

◆ operator*=()

template<class B , class A = std::allocator<B>>
BCRSMatrix & Dune::BCRSMatrix< B, A >::operator*= ( const field_type k)
inline

vector space multiplication with scalar

◆ operator+=()

template<class B , class A = std::allocator<B>>
BCRSMatrix & Dune::BCRSMatrix< B, A >::operator+= ( const BCRSMatrix< B, A > &  b)
inline

Add the entries of another matrix to this one.

Parameters
bThe matrix to add to this one. Its sparsity pattern has to be subset of the sparsity pattern of this matrix.

◆ operator-=()

template<class B , class A = std::allocator<B>>
BCRSMatrix & Dune::BCRSMatrix< B, A >::operator-= ( const BCRSMatrix< B, A > &  b)
inline

Subtract the entries of another matrix from this one.

Parameters
bThe matrix to subtract from this one. Its sparsity pattern has to be subset of the sparsity pattern of this matrix.

◆ operator/=()

template<class B , class A = std::allocator<B>>
BCRSMatrix & Dune::BCRSMatrix< B, A >::operator/= ( const field_type k)
inline

vector space division by scalar

◆ operator=() [1/2]

template<class B , class A = std::allocator<B>>
BCRSMatrix & Dune::BCRSMatrix< B, A >::operator= ( const BCRSMatrix< B, A > &  Mat)
inline

assignment

Frees and reallocates space. Both sparsity pattern and values are set from Mat.

◆ operator=() [2/2]

template<class B , class A = std::allocator<B>>
BCRSMatrix & Dune::BCRSMatrix< B, A >::operator= ( const field_type k)
inline

Assignment from a scalar.

◆ operator[]() [1/2]

template<class B , class A = std::allocator<B>>
row_type & Dune::BCRSMatrix< B, A >::operator[] ( size_type  i)
inline

random access to the rows

◆ operator[]() [2/2]

template<class B , class A = std::allocator<B>>
const row_type & Dune::BCRSMatrix< B, A >::operator[] ( size_type  i) const
inline

same for read only access

◆ setBuildMode()

template<class B , class A = std::allocator<B>>
void Dune::BCRSMatrix< B, A >::setBuildMode ( BuildMode  bm)
inline

Sets the build mode of the matrix.

Parameters
bmThe build mode to use.

◆ setColumnPointers()

template<class B , class A = std::allocator<B>>
void Dune::BCRSMatrix< B, A >::setColumnPointers ( ConstRowIterator  row)
inlineprotected

Copy row sizes from iterator range starting at row and set column index pointers for all rows.

This method does not modify the data pointers, as those are set only after building the pattern (to allow for a delayed allocation).

◆ setDataPointers()

template<class B , class A = std::allocator<B>>
void Dune::BCRSMatrix< B, A >::setDataPointers ( )
inlineprotected

Set data pointers for all rows.

This method assumes that column pointers and row sizes have been correctly set up by a prior call to setColumnPointers().

◆ setImplicitBuildModeParameters()

template<class B , class A = std::allocator<B>>
void Dune::BCRSMatrix< B, A >::setImplicitBuildModeParameters ( size_type  _avg,
double  compressionBufferSize 
)
inline

Set parameters needed for creation in implicit build mode.

Use this method before setSize() to define storage behaviour of a matrix in implicit build mode

Parameters
_avgexpected average number of entries per row
compressionBufferSizefraction of _n*_avg which is expected to be needed for elements that exceed _avg entries per row.

◆ setIndices()

template<class B , class A = std::allocator<B>>
template<typename It >
void Dune::BCRSMatrix< B, A >::setIndices ( size_type  row,
It  begin,
It  end 
)
inline

Set all column indices for row from the given iterator range.

The iterator range has to be of the same length as the previously set row size. The entries in the iterator range do not have to be in any particular order, but must not contain duplicate values.

Calling this method overwrites any previously set column indices!

◆ setrowsize()

template<class B , class A = std::allocator<B>>
void Dune::BCRSMatrix< B, A >::setrowsize ( size_type  i,
size_type  s 
)
inline

Set number of indices in row i to s.

The number s may actually be larger than the true number of nonzero entries in row i. In that case, the extra memory goes wasted. You will receive run-time warnings about this, sent to the Dune::dwarn stream.

◆ setSize()

template<class B , class A = std::allocator<B>>
void Dune::BCRSMatrix< B, A >::setSize ( size_type  rows,
size_type  columns,
size_type  nnz = 0 
)
inline

Set the size of the matrix.

Sets the number of rows and columns of the matrix and allocates the memory needed for the storage of the matrix entries.

Warning
After calling this methods on an already allocated (and probably setup matrix) results in all the structure and data being deleted. I.~e. one has to setup the matrix again.
Parameters
rowsThe number of rows the matrix should contain.
columnsthe number of columns the matrix should contain.
nnzThe number of nonzero entries the matrix should hold (if omitted defaults to 0). Must be omitted in implicit mode.

◆ setWindowPointers()

template<class B , class A = std::allocator<B>>
void Dune::BCRSMatrix< B, A >::setWindowPointers ( ConstRowIterator  row)
inlineprotected

◆ umhv()

template<class B , class A = std::allocator<B>>
template<class X , class Y >
void Dune::BCRSMatrix< B, A >::umhv ( const X &  x,
Y &  y 
) const
inline

y += A^H x

◆ umtv()

template<class B , class A = std::allocator<B>>
template<class X , class Y >
void Dune::BCRSMatrix< B, A >::umtv ( const X &  x,
Y &  y 
) const
inline

y += A^T x

◆ umv()

template<class B , class A = std::allocator<B>>
template<class X , class Y >
void Dune::BCRSMatrix< B, A >::umv ( const X &  x,
Y &  y 
) const
inline

y += A x

◆ usmhv()

template<class B , class A = std::allocator<B>>
template<class X , class Y >
void Dune::BCRSMatrix< B, A >::usmhv ( const field_type alpha,
const X &  x,
Y &  y 
) const
inline

y += alpha A^H x

◆ usmtv()

template<class B , class A = std::allocator<B>>
template<class X , class Y >
void Dune::BCRSMatrix< B, A >::usmtv ( const field_type alpha,
const X &  x,
Y &  y 
) const
inline

y += alpha A^T x

◆ usmv()

template<class B , class A = std::allocator<B>>
template<class X , class Y , class F >
void Dune::BCRSMatrix< B, A >::usmv ( F &&  alpha,
const X &  x,
Y &  y 
) const
inline

y += alpha A x

Member Data Documentation

◆ a

template<class B , class A = std::allocator<B>>
B* Dune::BCRSMatrix< B, A >::a
protected

◆ allocationSize_

template<class B , class A = std::allocator<B>>
size_type Dune::BCRSMatrix< B, A >::allocationSize_
protected

◆ allocator_

template<class B , class A = std::allocator<B>>
std::allocator_traits<A>::template rebind_alloc<B> Dune::BCRSMatrix< B, A >::allocator_
protected

◆ avg

template<class B , class A = std::allocator<B>>
size_type Dune::BCRSMatrix< B, A >::avg
protected

◆ blocklevel

template<class B , class A = std::allocator<B>>
constexpr unsigned int Dune::BCRSMatrix< B, A >::blocklevel = blockLevel<B>()+1
staticconstexpr

increment block level counter

◆ build_mode

template<class B , class A = std::allocator<B>>
BuildMode Dune::BCRSMatrix< B, A >::build_mode
protected

◆ compressionBufferSize_

template<class B , class A = std::allocator<B>>
double Dune::BCRSMatrix< B, A >::compressionBufferSize_
protected

◆ j_

template<class B , class A = std::allocator<B>>
std::shared_ptr<size_type> Dune::BCRSMatrix< B, A >::j_
protected

◆ m

template<class B , class A = std::allocator<B>>
size_type Dune::BCRSMatrix< B, A >::m
protected

◆ n

template<class B , class A = std::allocator<B>>
size_type Dune::BCRSMatrix< B, A >::n
protected

◆ nnz_

template<class B , class A = std::allocator<B>>
size_type Dune::BCRSMatrix< B, A >::nnz_
mutableprotected

◆ overflow

template<class B , class A = std::allocator<B>>
OverflowType Dune::BCRSMatrix< B, A >::overflow
protected

◆ r

template<class B , class A = std::allocator<B>>
row_type* Dune::BCRSMatrix< B, A >::r
protected

◆ ready

template<class B , class A = std::allocator<B>>
BuildStage Dune::BCRSMatrix< B, A >::ready
protected

◆ rowAllocator_

template<class B , class A = std::allocator<B>>
std::allocator_traits<A>::template rebind_alloc<row_type> Dune::BCRSMatrix< B, A >::rowAllocator_
protected

◆ sizeAllocator_

template<class B , class A = std::allocator<B>>
std::allocator_traits<A>::template rebind_alloc<size_type> Dune::BCRSMatrix< B, A >::sizeAllocator_
protected

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