Reference documentation for deal.II version Git 5109843 2018-03-21 23:56:40 +0700
SparsityPattern Class Reference

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

Inheritance diagram for SparsityPattern:
[legend]

Public Types

typedef types::global_dof_index size_type

typedef SparsityPatternIterators::Iterator const_iterator

typedef SparsityPatternIterators::Iterator iterator

Public Member Functions

Construction and setup Constructors, destructor; functions

initializing, copying and filling an object.

SparsityPattern ()

SparsityPattern (const SparsityPattern &)

SparsityPattern (const size_type m, const size_type n, const unsigned int max_per_row)

SparsityPattern (const size_type m, const size_type n, const std::vector< unsigned int > &row_lengths)

SparsityPattern (const size_type m, const unsigned int max_per_row)

SparsityPattern (const size_type m, const std::vector< unsigned int > &row_lengths)

SparsityPattern (const SparsityPattern &original, const unsigned int max_per_row, const size_type extra_off_diagonals)

~SparsityPattern ()=default

SparsityPatternoperator= (const SparsityPattern &)

void reinit (const size_type m, const size_type n, const unsigned int max_per_row)

Public Member Functions inherited from Subscriptor
Subscriptor ()

Subscriptor (const Subscriptor &)

Subscriptor (Subscriptor &&) noexcept

virtual ~Subscriptor ()

Subscriptoroperator= (const Subscriptor &)

Subscriptoroperator= (Subscriptor &&) noexcept

void subscribe (const char *identifier=nullptr) const

void unsubscribe (const char *identifier=nullptr) const

unsigned int n_subscriptions () const

void list_subscribers () const

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

Static Public Attributes

static const size_type invalid_entry = numbers::invalid_size_type

Additional Inherited Members

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

static::ExceptionBase & ExcNoSubscriber (char *arg1, char *arg2)

Detailed Description

A class that can store which elements of a matrix are nonzero (or, in fact, may be nonzero) and for which we have to allocate memory to store their values. This class is an example of the "static" type of sparsity patters (see Sparsity patterns). It uses the compressed row storage (CSR) format to store data, and is used as the basis for the SparseMatrix class.

The elements of a SparsityPattern, corresponding to the places where SparseMatrix objects can store nonzero entries, are stored row-by-row. Within each row, elements are generally stored left-to-right in increasing column index order; the exception to this rule is that if the matrix is square (n_rows() == n_columns()), then the diagonal entry is stored as the first element in each row to make operations like applying a Jacobi or SSOR preconditioner faster. As a consequence, if you traverse the elements of a row of a SparsityPattern with the help of iterators into this object (using SparsityPattern::begin and SparsityPattern::end) you will find that the elements are not sorted by column index within each row whenever the matrix is square (the first item will be the diagonal, followed by the other entries sorted by column index).

Note
While this class forms the basis upon which SparseMatrix objects base their storage format, and thus plays a central role in setting up linear systems, it is rarely set up directly due to the way it stores its information. Rather, one typically goes through an intermediate format first, see for example the step-2 tutorial program as well as the documentation module Sparsity patterns.

Definition at line 342 of file sparsity_pattern.h.

Member Typedef Documentation

Declare type for container size.

Definition at line 348 of file sparsity_pattern.h.

Typedef an iterator class that allows to walk over all nonzero elements of a sparsity pattern.

Definition at line 356 of file sparsity_pattern.h.

Typedef an iterator class that allows to walk over all nonzero elements of a sparsity pattern.

Since the iterator does not allow to modify the sparsity pattern, this type is the same as that for const_iterator.

Definition at line 367 of file sparsity_pattern.h.

Constructor & Destructor Documentation

 SparsityPattern::SparsityPattern ( )

Initialize the matrix empty, that is with no memory allocated. This is useful if you want such objects as member variables in other classes. You can make the structure usable by calling the reinit() function.

Definition at line 41 of file sparsity_pattern.cc.

 SparsityPattern::SparsityPattern ( const SparsityPattern & s )

Copy constructor. This constructor is only allowed to be called if the matrix structure to be copied is empty. This is so in order to prevent involuntary copies of objects for temporaries, which can use large amounts of computing time. However, copy constructors are needed if one wants to place a SparsityPattern in a container, e.g., to write such statements like v.push_back (SparsityPattern());, with v a std::vector of SparsityPattern objects.

Usually, it is sufficient to use the explicit keyword to disallow unwanted temporaries, but this does not work for std::vectors. Since copying a structure like this is not useful anyway because multiple matrices can use the same sparsity structure, copies are only allowed for empty objects, as described above.

Definition at line 55 of file sparsity_pattern.cc.

 SparsityPattern::SparsityPattern ( const size_type m, const size_type n, const unsigned int max_per_row )

Initialize a rectangular pattern of size m x n.

Parameters
 [in] m The number of rows. [in] n The number of columns. [in] max_per_row Maximum number of nonzero entries per row.

Definition at line 76 of file sparsity_pattern.cc.

 SparsityPattern::SparsityPattern ( const size_type m, const size_type n, const std::vector< unsigned int > & row_lengths )

Initialize a rectangular pattern of size m x n.

Parameters
 [in] m The number of rows. [in] n The number of columns. [in] row_lengths Possible number of nonzero entries for each row. This vector must have one entry for each row.

Definition at line 92 of file sparsity_pattern.cc.

 SparsityPattern::SparsityPattern ( const size_type m, const unsigned int max_per_row )

Initialize a quadratic pattern of dimension m with at most max_per_row nonzero entries per row.

This constructor automatically enables optimized storage of diagonal elements. To avoid this, use the constructor taking row and column numbers separately.

Definition at line 107 of file sparsity_pattern.cc.

 SparsityPattern::SparsityPattern ( const size_type m, const std::vector< unsigned int > & row_lengths )

Initialize a quadratic pattern of size m x m.

Parameters
 [in] m The number of rows and columns. [in] row_lengths Maximum number of nonzero entries for each row. This vector must have one entry for each row.

Definition at line 120 of file sparsity_pattern.cc.

 SparsityPattern::SparsityPattern ( const SparsityPattern & original, const unsigned int max_per_row, const size_type extra_off_diagonals )

Make a copy with extra off-diagonals.

This constructs objects intended for the application of the ILU(n)-method or other incomplete decompositions. Therefore, additional to the original entry structure, space for extra_off_diagonals side- diagonals is provided on both sides of the main diagonal.

max_per_row is the maximum number of nonzero elements per row which this structure is to hold. It is assumed that this number is sufficiently large to accommodate both the elements in original as well as the new off-diagonal elements created by this constructor. You will usually want to give the same number as you gave for original plus the number of side diagonals times two. You may however give a larger value if you wish to add further nonzero entries for the decomposition based on other criteria than their being on side- diagonals.

This function requires that original refers to a quadratic matrix structure. It must be compressed. The matrix structure is not compressed after this function finishes.

Definition at line 133 of file sparsity_pattern.cc.

 SparsityPattern::~SparsityPattern ( )
default

Destructor.

Member Function Documentation

 SparsityPattern & SparsityPattern::operator= ( const SparsityPattern & s )

Copy operator. For this the same holds as for the copy constructor: it is declared, defined and fine to be called, but the latter only for empty objects.

Definition at line 219 of file sparsity_pattern.cc.

 void SparsityPattern::reinit ( const size_type m, const size_type n, const unsigned int max_per_row )

Reallocate memory and set up data structures for a new matrix with m rows and n columns, with at most max_per_row nonzero entries per row.

This function simply maps its operations to the other reinit() function.

Definition at line 237 of file sparsity_pattern.cc.

Member Data Documentation

 const SparsityPattern::size_type SparsityPattern::invalid_entry = numbers::invalid_size_type
static

Define a value which is used to indicate that a certain value in the #colnums array is unused, i.e. does not represent a certain column number index.

Indices with this invalid value are used to insert new entries to the sparsity pattern using the add() member function, and are removed when calling compress().

You should not assume that the variable declared here has a certain value. The initialization is given here only to enable the compiler to perform some optimizations, but the actual value of the variable may change over time.

Definition at line 384 of file sparsity_pattern.h.

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