Reference documentation for deal.II version 9.2.0
\(\newcommand{\dealvcentcolon}{\mathrel{\mathop{:}}}\) \(\newcommand{\dealcoloneq}{\dealvcentcolon\mathrel{\mkern-1.2mu}=}\) \(\newcommand{\jump}[1]{\left[\!\left[ #1 \right]\!\right]}\) \(\newcommand{\average}[1]{\left\{\!\left\{ #1 \right\}\!\right\}}\)
Classes | Public Types | List of all members
SparseMatrixEZ< number > Class Template Reference

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

Inheritance diagram for SparseMatrixEZ< number >:
[legend]

Classes

class  const_iterator
 
struct  Entry
 
struct  RowInfo
 

Public Types

using size_type = types::global_dof_index
 
using value_type = number
 

Public Member Functions

Constructors and initialization
 SparseMatrixEZ ()
 
 SparseMatrixEZ (const SparseMatrixEZ &)
 
 SparseMatrixEZ (const size_type n_rows, const size_type n_columns, const size_type default_row_length=0, const unsigned int default_increment=1)
 
 ~SparseMatrixEZ () override=default
 
SparseMatrixEZ< number > & operator= (const SparseMatrixEZ< number > &)
 
SparseMatrixEZ< number > & operator= (const double d)
 
void reinit (const size_type n_rows, const size_type n_columns, size_type default_row_length=0, unsigned int default_increment=1, size_type reserve=0)
 
void clear ()
 
Information on the matrix
bool empty () const
 
size_type m () const
 
size_type n () const
 
size_type get_row_length (const size_type row) const
 
size_type n_nonzero_elements () const
 
std::size_t memory_consumption () const
 
template<class StreamType >
void print_statistics (StreamType &s, bool full=false)
 
void compute_statistics (size_type &used, size_type &allocated, size_type &reserved, std::vector< size_type > &used_by_line, const bool compute_by_line) const
 
Modifying entries
void set (const size_type i, const size_type j, const number value, const bool elide_zero_values=true)
 
void add (const size_type i, const size_type j, const number value)
 
template<typename number2 >
void add (const std::vector< size_type > &indices, const FullMatrix< number2 > &full_matrix, const bool elide_zero_values=true)
 
template<typename number2 >
void add (const std::vector< size_type > &row_indices, const std::vector< size_type > &col_indices, const FullMatrix< number2 > &full_matrix, const bool elide_zero_values=true)
 
template<typename number2 >
void add (const size_type row, const std::vector< size_type > &col_indices, const std::vector< number2 > &values, const bool elide_zero_values=true)
 
template<typename number2 >
void add (const size_type row, const size_type n_cols, const size_type *col_indices, const number2 *values, const bool elide_zero_values=true, const bool col_indices_are_sorted=false)
 
template<typename MatrixType >
SparseMatrixEZ< number > & copy_from (const MatrixType &source, const bool elide_zero_values=true)
 
template<typename MatrixType >
void add (const number factor, const MatrixType &matrix)
 
Entry Access
number operator() (const size_type i, const size_type j) const
 
number el (const size_type i, const size_type j) const
 
Multiplications
template<typename somenumber >
void vmult (Vector< somenumber > &dst, const Vector< somenumber > &src) const
 
template<typename somenumber >
void Tvmult (Vector< somenumber > &dst, const Vector< somenumber > &src) const
 
template<typename somenumber >
void vmult_add (Vector< somenumber > &dst, const Vector< somenumber > &src) const
 
template<typename somenumber >
void Tvmult_add (Vector< somenumber > &dst, const Vector< somenumber > &src) const
 
Matrix norms
number l2_norm () const
 
Preconditioning methods
template<typename somenumber >
void precondition_Jacobi (Vector< somenumber > &dst, const Vector< somenumber > &src, const number omega=1.) const
 
template<typename somenumber >
void precondition_SSOR (Vector< somenumber > &dst, const Vector< somenumber > &src, const number om=1., const std::vector< std::size_t > &pos_right_of_diagonal=std::vector< std::size_t >()) const
 
template<typename somenumber >
void precondition_SOR (Vector< somenumber > &dst, const Vector< somenumber > &src, const number om=1.) const
 
template<typename somenumber >
void precondition_TSOR (Vector< somenumber > &dst, const Vector< somenumber > &src, const number om=1.) const
 
template<typename MatrixTypeA , typename MatrixTypeB >
void conjugate_add (const MatrixTypeA &A, const MatrixTypeB &B, const bool transpose=false)
 
Iterators
const_iterator begin () const
 
const_iterator end () const
 
const_iterator begin (const size_type r) const
 
const_iterator end (const size_type r) 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)
 

Input/Output

size_type n_columns
 
std::vector< RowInforow_info
 
std::vector< Entrydata
 
unsigned int increment
 
unsigned int saved_default_row_length
 
void print (std::ostream &out) const
 
void print_formatted (std::ostream &out, const unsigned int precision=3, const bool scientific=true, const unsigned int width=0, const char *zero_string=" ", const double denominator=1.) const
 
void block_write (std::ostream &out) const
 
void block_read (std::istream &in)
 
static ::ExceptionBaseExcNoDiagonal ()
 
static ::ExceptionBaseExcInvalidEntry (int arg1, int arg2)
 
static ::ExceptionBaseExcEntryAllocationFailure (int arg1, int arg2)
 
const Entrylocate (const size_type row, const size_type col) const
 
Entrylocate (const size_type row, const size_type col)
 
Entryallocate (const size_type row, const size_type col)
 
template<typename somenumber >
void threaded_vmult (Vector< somenumber > &dst, const Vector< somenumber > &src, const size_type begin_row, const size_type end_row) const
 
template<typename somenumber >
void threaded_matrix_norm_square (const Vector< somenumber > &v, const size_type begin_row, const size_type end_row, somenumber *partial_sum) const
 
template<typename somenumber >
void threaded_matrix_scalar_product (const Vector< somenumber > &u, const Vector< somenumber > &v, const size_type begin_row, const size_type end_row, somenumber *partial_sum) const
 

Additional Inherited Members

- 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)
 

Detailed Description

template<typename number>
class SparseMatrixEZ< number >

Sparse matrix without sparsity pattern.

Instead of using a pre-assembled sparsity pattern, this matrix builds the pattern on the fly. Filling the matrix may consume more time than for SparseMatrix, since large memory movements may be involved when new matrix elements are inserted somewhere in the middle of the matrix and no currently unused memory locations are available for the row into which the new entry is to be inserted. To help optimize things, an expected row-length may be provided to the constructor, as well as an increment size for rows.

This class uses a storage structure that, similar to the usual sparse matrix format, only stores non-zero elements. These are stored in a single data array for the entire matrix, and are ordered by row and, within each row, by column number. A separate array describes where in the long data array each row starts and how long it is.

Due to this structure, gaps may occur between rows. Whenever a new entry must be created, an attempt is made to use the gap in its row. If no gap is left, the row must be extended and all subsequent rows must be shifted backwards. This is a very expensive operation and explains the inefficiency of this data structure and why it is useful to pre-allocate a sparsity pattern as the SparseMatrix class does.

This is where the optimization parameters, provided to the constructor or to the reinit() functions come in. default_row_length is the number of entries that will be allocated for each row on initialization (the actual length of the rows is still zero). This means, that default_row_length entries can be added to this row without shifting other rows. If fewer entries are added, the additional memory will of course be wasted.

If the space for a row is not sufficient, then it is enlarged by default_increment entries. This way, subsequent rows are not shifted by single entries very often.

Finally, the default_reserve allocates extra space at the end of the data array. This space is used whenever any row must be enlarged. It is important because otherwise not only the following rows must be moved, but in fact all rows after allocating sufficiently much space for the entire data array.

Suggested settings: default_row_length should be the length of a typical row, for instance the size of the stencil in regular parts of the grid. Then, default_increment may be the expected amount of entries added to the row by having one hanging node. This way, a good compromise between memory consumption and speed should be achieved. default_reserve should then be an estimate for the number of hanging nodes times default_increment.

Letting default_increment be zero causes an exception whenever a row overflows.

If the rows are expected to be filled more or less from first to last, using a default_row_length of zero may not be such a bad idea.

Note
The name of the class makes sense by pronouncing it the American way, where "EZ" is pronounced the same way as the word "easy".
Author
Guido Kanschat
Date
2002, 2010

Definition at line 107 of file sparse_matrix_ez.h.

Member Typedef Documentation

◆ size_type

template<typename number >
using SparseMatrixEZ< number >::size_type = types::global_dof_index

Declare type for container size.

Definition at line 113 of file sparse_matrix_ez.h.

◆ value_type

template<typename number >
using SparseMatrixEZ< number >::value_type = number

Type of matrix entries. This alias is analogous to value_type in the standard library containers.

Definition at line 295 of file sparse_matrix_ez.h.

Constructor & Destructor Documentation

◆ SparseMatrixEZ() [1/3]

template<typename number >
SparseMatrixEZ< number >::SparseMatrixEZ ( )

Constructor. Initializes an empty matrix of dimension zero times zero.

◆ SparseMatrixEZ() [2/3]

template<typename number >
SparseMatrixEZ< number >::SparseMatrixEZ ( const SparseMatrixEZ< number > &  )

Dummy copy constructor. This is here for use in containers. It may only be called for empty objects.

If you really want to copy a whole matrix, you can do so by using the copy_from function.

◆ SparseMatrixEZ() [3/3]

template<typename number >
SparseMatrixEZ< number >::SparseMatrixEZ ( const size_type  n_rows,
const size_type  n_columns,
const size_type  default_row_length = 0,
const unsigned int  default_increment = 1 
)
explicit

Constructor. Generates a matrix of the given size, ready to be filled. The optional parameters default_row_length and default_increment allow for preallocating memory. Providing these properly is essential for an efficient assembling of the matrix.

◆ ~SparseMatrixEZ()

template<typename number >
SparseMatrixEZ< number >::~SparseMatrixEZ ( )
overridedefault

Destructor. Free all memory.

Member Function Documentation

◆ operator=() [1/2]

template<typename number >
SparseMatrixEZ<number>& SparseMatrixEZ< number >::operator= ( const SparseMatrixEZ< number > &  )

Pseudo operator only copying empty objects.

◆ operator=() [2/2]

template<typename number >
SparseMatrixEZ<number>& SparseMatrixEZ< number >::operator= ( const double  d)

This operator assigns a scalar to a matrix. Since this does usually not make much sense (should we set all matrix entries to this value? Only the nonzero entries of the sparsity pattern?), this operation is only allowed if the actual value to be assigned is zero. This operator only exists to allow for the obvious notation matrix=0, which sets all elements of the matrix to zero, but keep the sparsity pattern previously used.

◆ reinit()

template<typename number >
void SparseMatrixEZ< number >::reinit ( const size_type  n_rows,
const size_type  n_columns,
size_type  default_row_length = 0,
unsigned int  default_increment = 1,
size_type  reserve = 0 
)

Reinitialize the sparse matrix to the dimensions provided. The matrix will have no entries at this point. The optional parameters default_row_length, default_increment and reserve allow for preallocating memory. Providing these properly is essential for an efficient assembling of the matrix.

◆ clear()

template<typename number >
void SparseMatrixEZ< number >::clear ( )

Release all memory and return to a state just like after having called the default constructor. It also forgets its sparsity pattern.

◆ empty()

template<typename number >
bool SparseMatrixEZ< number >::empty ( ) const

Return whether the object is empty. It is empty if both dimensions are zero.

◆ m()

template<typename number >
SparseMatrixEZ< number >::size_type SparseMatrixEZ< number >::m
inline

Return the dimension of the codomain (or range) space. Note that the matrix is of dimension \(m \times n\).

Definition at line 1089 of file sparse_matrix_ez.h.

◆ n()

template<typename number >
SparseMatrixEZ< number >::size_type SparseMatrixEZ< number >::n
inline

Return the dimension of the domain space. Note that the matrix is of dimension \(m \times n\).

Definition at line 1097 of file sparse_matrix_ez.h.

◆ get_row_length()

template<typename number >
size_type SparseMatrixEZ< number >::get_row_length ( const size_type  row) const

Return the number of entries in a specific row.

◆ n_nonzero_elements()

template<typename number >
size_type SparseMatrixEZ< number >::n_nonzero_elements ( ) const

Return the number of nonzero elements of this matrix.

◆ memory_consumption()

template<typename number >
std::size_t SparseMatrixEZ< number >::memory_consumption ( ) const

Determine an estimate for the memory consumption (in bytes) of this object.

◆ print_statistics()

template<typename number >
template<class StreamType >
void SparseMatrixEZ< number >::print_statistics ( StreamType &  s,
bool  full = false 
)
inline

Print statistics. If full is true, prints a histogram of all existing row lengths and allocated row lengths. Otherwise, just the relation of allocated and used entries is shown.

Definition at line 1570 of file sparse_matrix_ez.h.

◆ compute_statistics()

template<typename number >
void SparseMatrixEZ< number >::compute_statistics ( size_type used,
size_type allocated,
size_type reserved,
std::vector< size_type > &  used_by_line,
const bool  compute_by_line 
) const

Compute numbers of entries.

In the first three arguments, this function returns the number of entries used, allocated and reserved by this matrix.

If the final argument is true, the number of entries in each line is printed as well.

◆ set()

template<typename number >
void SparseMatrixEZ< number >::set ( const size_type  i,
const size_type  j,
const number  value,
const bool  elide_zero_values = true 
)
inline

Set the element (i,j) to value.

If value is not a finite number an exception is thrown.

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.

If anyway a new element will be inserted and it does not exist, allocates the entry.

Note
You may need to insert some zero elements to keep a symmetric sparsity pattern for the matrix.

Definition at line 1234 of file sparse_matrix_ez.h.

◆ add() [1/6]

template<typename number >
void SparseMatrixEZ< number >::add ( const size_type  i,
const size_type  j,
const number  value 
)
inline

Add value to the element (i,j). Allocates the entry if it does not exist. Filters out zeroes automatically. If value is not a finite number an exception is thrown.

Definition at line 1261 of file sparse_matrix_ez.h.

◆ add() [2/6]

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

Add all elements given in a FullMatrix<double> into sparse matrix locations given by indices. In other words, this function adds the elements in full_matrix to the respective entries in calling matrix, using the local-to-global indexing specified by indices for both the rows and the columns of the matrix. This function assumes a quadratic sparse matrix and a quadratic full_matrix, the usual situation in FE calculations.

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 1282 of file sparse_matrix_ez.h.

◆ add() [3/6]

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

Same function as before, but now including the possibility to use rectangular full_matrices and different local-to-global indexing on rows and columns, respectively.

Definition at line 1298 of file sparse_matrix_ez.h.

◆ add() [4/6]

template<typename number >
template<typename number2 >
void SparseMatrixEZ< number >::add ( const size_type  row,
const std::vector< size_type > &  col_indices,
const std::vector< number2 > &  values,
const bool  elide_zero_values = true 
)

Set several elements in the specified row of the matrix with column indices as given by col_indices to the respective value.

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 1315 of file sparse_matrix_ez.h.

◆ add() [5/6]

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

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 1331 of file sparse_matrix_ez.h.

◆ copy_from()

template<typename number >
template<typename MatrixType >
SparseMatrixEZ< number > & SparseMatrixEZ< number >::copy_from ( const MatrixType &  source,
const bool  elide_zero_values = true 
)
inline

Copy the matrix given as argument into the current object.

Copying matrices is an expensive operation that we do not want to happen by accident through compiler generated code for operator=. (This would happen, for example, if one accidentally declared a function argument of the current type by value rather than by reference.) The functionality of copying matrices is implemented in this member function instead. All copy operations of objects of this type therefore require an explicit function call.

The source matrix may be a matrix of arbitrary type, as long as its data type is convertible to the data type of this 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.

The function returns a reference to this.

Definition at line 1406 of file sparse_matrix_ez.h.

◆ add() [6/6]

template<typename number >
template<typename MatrixType >
void SparseMatrixEZ< number >::add ( const number  factor,
const MatrixType &  matrix 
)
inline

Add matrix scaled by factor to this matrix.

The source matrix may be a matrix of arbitrary type, as long as its data type is convertible to the data type of this matrix and it has the standard const_iterator.

Definition at line 1429 of file sparse_matrix_ez.h.

◆ operator()()

template<typename number >
number SparseMatrixEZ< number >::operator() ( const size_type  i,
const size_type  j 
) const
inline

Return the value of the entry (i,j). This may be an expensive operation and you should always take care where to call this function. In order to avoid abuse, this function throws an exception if the required element does not exist in the matrix.

In case you want a function that returns zero instead (for entries that are not in the sparsity pattern of the matrix), use the el function.

Definition at line 1360 of file sparse_matrix_ez.h.

◆ el()

template<typename number >
number SparseMatrixEZ< number >::el ( const size_type  i,
const size_type  j 
) const
inline

Return the value of the entry (i,j). Returns zero for all non-existing entries.

Definition at line 1348 of file sparse_matrix_ez.h.

◆ vmult()

template<typename number >
template<typename somenumber >
void SparseMatrixEZ< number >::vmult ( Vector< somenumber > &  dst,
const Vector< somenumber > &  src 
) const

Matrix-vector multiplication: let \(dst = M*src\) with \(M\) being this matrix.

◆ Tvmult()

template<typename number >
template<typename somenumber >
void SparseMatrixEZ< number >::Tvmult ( Vector< somenumber > &  dst,
const Vector< somenumber > &  src 
) const

Matrix-vector multiplication: let \(dst = M^T*src\) with \(M\) being this matrix. This function does the same as vmult but takes the transposed matrix.

◆ vmult_add()

template<typename number >
template<typename somenumber >
void SparseMatrixEZ< number >::vmult_add ( Vector< somenumber > &  dst,
const Vector< somenumber > &  src 
) const

Adding Matrix-vector multiplication. Add \(M*src\) on \(dst\) with \(M\) being this matrix.

◆ Tvmult_add()

template<typename number >
template<typename somenumber >
void SparseMatrixEZ< number >::Tvmult_add ( Vector< somenumber > &  dst,
const Vector< somenumber > &  src 
) const

Adding Matrix-vector multiplication. Add \(M^T*src\) to \(dst\) with \(M\) being this matrix. This function does the same as vmult_add but takes the transposed matrix.

◆ l2_norm()

template<typename number >
number SparseMatrixEZ< number >::l2_norm ( ) const

Frobenius-norm of the matrix.

◆ precondition_Jacobi()

template<typename number >
template<typename somenumber >
void SparseMatrixEZ< number >::precondition_Jacobi ( Vector< somenumber > &  dst,
const Vector< somenumber > &  src,
const number  omega = 1. 
) const

Apply the Jacobi preconditioner, which multiplies every element of the src vector by the inverse of the respective diagonal element and multiplies the result with the damping factor omega.

◆ precondition_SSOR()

template<typename number >
template<typename somenumber >
void SparseMatrixEZ< number >::precondition_SSOR ( Vector< somenumber > &  dst,
const Vector< somenumber > &  src,
const number  om = 1.,
const std::vector< std::size_t > &  pos_right_of_diagonal = std::vector< std::size_t >() 
) const

Apply SSOR preconditioning to src.

◆ precondition_SOR()

template<typename number >
template<typename somenumber >
void SparseMatrixEZ< number >::precondition_SOR ( Vector< somenumber > &  dst,
const Vector< somenumber > &  src,
const number  om = 1. 
) const

Apply SOR preconditioning matrix to src. The result of this method is \(dst = (om D - L)^{-1} src\).

◆ precondition_TSOR()

template<typename number >
template<typename somenumber >
void SparseMatrixEZ< number >::precondition_TSOR ( Vector< somenumber > &  dst,
const Vector< somenumber > &  src,
const number  om = 1. 
) const

Apply transpose SOR preconditioning matrix to src. The result of this method is \(dst = (om D - U)^{-1} src\).

◆ conjugate_add()

template<typename number >
template<typename MatrixTypeA , typename MatrixTypeB >
void SparseMatrixEZ< number >::conjugate_add ( const MatrixTypeA &  A,
const MatrixTypeB &  B,
const bool  transpose = false 
)
inline

Add the matrix A conjugated by B, that is, \(B A B^T\) to this object. If the parameter transpose is true, compute \(B^T A B\).

This function requires that B has a const_iterator traversing all matrix entries and that A has a function el(i,j) for access to a specific entry.

Definition at line 1456 of file sparse_matrix_ez.h.

◆ begin() [1/2]

template<typename number >
SparseMatrixEZ< number >::const_iterator SparseMatrixEZ< number >::begin
inline

Iterator starting at the first existing entry.

Definition at line 1372 of file sparse_matrix_ez.h.

◆ end() [1/2]

template<typename number >
SparseMatrixEZ< number >::const_iterator SparseMatrixEZ< number >::end
inline

Final iterator.

Definition at line 1380 of file sparse_matrix_ez.h.

◆ begin() [2/2]

template<typename number >
SparseMatrixEZ< number >::const_iterator SparseMatrixEZ< number >::begin ( const size_type  r) const
inline

Iterator starting at the first entry of row r. If this row is empty, the result is end(r), which does NOT point into row r.

Definition at line 1387 of file sparse_matrix_ez.h.

◆ end() [2/2]

template<typename number >
SparseMatrixEZ< number >::const_iterator SparseMatrixEZ< number >::end ( const size_type  r) const
inline

Final iterator of row r. The result may be different from end()!

Definition at line 1396 of file sparse_matrix_ez.h.


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