Classes | |
class | ExcPETScError |
class | ExcSourceEqualsDestination |
struct | LastAction |
Public Types | |
typedef MatrixIterators::const_iterator | const_iterator |
typedef PetscScalar | value_type |
Public Member Functions | |
MatrixBase () | |
virtual | ~MatrixBase () |
MatrixBase & | operator= (const double d) |
void | clear () |
void | set (const unsigned int i, const unsigned int j, const PetscScalar value) |
void | set (const std::vector< unsigned int > &indices, const FullMatrix< PetscScalar > &full_matrix, const bool elide_zero_values=false) |
void | set (const std::vector< unsigned int > &row_indices, const std::vector< unsigned int > &col_indices, const FullMatrix< PetscScalar > &full_matrix, const bool elide_zero_values=false) |
void | set (const unsigned int row, const std::vector< unsigned int > &col_indices, const std::vector< PetscScalar > &values, const bool elide_zero_values=false) |
void | set (const unsigned int row, const unsigned int n_cols, const unsigned int *col_indices, const PetscScalar *values, const bool elide_zero_values=false) |
void | add (const unsigned int i, const unsigned int j, const PetscScalar value) |
void | add (const std::vector< unsigned int > &indices, const FullMatrix< PetscScalar > &full_matrix, const bool elide_zero_values=true) |
void | add (const std::vector< unsigned int > &row_indices, const std::vector< unsigned int > &col_indices, const FullMatrix< PetscScalar > &full_matrix, const bool elide_zero_values=true) |
void | add (const unsigned int row, const std::vector< unsigned int > &col_indices, const std::vector< PetscScalar > &values, const bool elide_zero_values=true) |
void | add (const unsigned int row, const unsigned int n_cols, const unsigned int *col_indices, const PetscScalar *values, const bool elide_zero_values=true, const bool col_indices_are_sorted=false) |
void | clear_row (const unsigned int row, const PetscScalar new_diag_value=0) |
void | clear_rows (const std::vector< unsigned int > &rows, const PetscScalar new_diag_value=0) |
void | compress () |
PetscScalar | operator() (const unsigned int i, const unsigned int j) const |
PetscScalar | el (const unsigned int i, const unsigned int j) const |
PetscScalar | diag_element (const unsigned int i) const |
unsigned int | m () const |
unsigned int | n () const |
unsigned int | local_size () const |
std::pair< unsigned int, unsigned int > | local_range () const |
bool | in_local_range (const unsigned int index) const |
virtual const MPI_Comm & | get_mpi_communicator () const =0 |
unsigned int | n_nonzero_elements () const |
unsigned int | row_length (const unsigned int row) const |
PetscReal | l1_norm () const |
PetscReal | linfty_norm () const |
PetscReal | frobenius_norm () const |
MatrixBase & | operator*= (const PetscScalar factor) |
MatrixBase & | operator/= (const PetscScalar factor) |
void | vmult (VectorBase &dst, const VectorBase &src) const |
void | Tvmult (VectorBase &dst, const VectorBase &src) const |
void | vmult_add (VectorBase &dst, const VectorBase &src) const |
void | Tvmult_add (VectorBase &dst, const VectorBase &src) const |
PetscScalar | matrix_norm_square (const VectorBase &v) const |
PetscScalar | matrix_scalar_product (const VectorBase &u, const VectorBase &v) const |
PetscScalar | residual (VectorBase &dst, const VectorBase &x, const VectorBase &b) const |
const_iterator | begin () const |
const_iterator | end () const |
const_iterator | begin (const unsigned int r) const |
const_iterator | end (const unsigned int r) const |
operator const Mat () const | |
void | transpose () |
PetscTruth | is_symmetric (const double tol=0.0) |
PetscTruth | is_hermitian (const double tol=0.0) |
void | write_ascii () |
Protected Attributes | |
Mat | matrix |
LastAction::Values | last_action |
Private Attributes | |
std::vector< unsigned int > | column_indices |
std::vector< PetscScalar > | column_values |
The interface of this class is modeled after the existing SparseMatrix class in deal.II. It has almost the same member functions, and is often exchangable. However, since PETSc only supports a single scalar type (either double, float, or a complex data type), it is not templated, and only works with whatever your PETSc installation has defined the data type PetscScalar to.
Note that PETSc only guarantees that operations do what you expect if the functions MatAssemblyBegin
and MatAssemblyEnd
have been called after matrix assembly. Therefore, you need to call SparseMatrix::compress() before you actually use the matrix. This also calls MatCompress
that compresses the storage format for sparse matrices by discarding unused elements. PETSc allows to continue with assembling the matrix after calls to these functions, but since there are no more free entries available after that any more, it is better to only call SparseMatrix::compress() once at the end of the assembly stage and before the matrix is actively used.
Declare a typedef for the iterator class.
typedef PetscScalar PETScWrappers::MatrixBase::value_type |
Declare a typedef in analogy to all the other container classes.
PETScWrappers::MatrixBase::MatrixBase | ( | ) |
Default constructor.
virtual PETScWrappers::MatrixBase::~MatrixBase | ( | ) | [virtual] |
Destructor. Made virtual so that one can use pointers to this class.
MatrixBase& PETScWrappers::MatrixBase::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 keeps the sparsity pattern previously used.
Reimplemented in PETScWrappers::MPI::SparseMatrix, and PETScWrappers::SparseMatrix.
void PETScWrappers::MatrixBase::clear | ( | ) |
Release all memory and return to a state just like after having called the default constructor.
void PETScWrappers::MatrixBase::set | ( | const unsigned int | i, | |
const unsigned int | j, | |||
const PetscScalar | value | |||
) |
Set the element (i,j) to value
.
If the present object (from a derived class of this one) happens to be a sparse matrix, then this function adds a new entry to the matrix if it didn't exist before, very much in contrast to the SparseMatrix class which throws an error if the entry does not exist. If value
is not a finite number an exception is thrown.
void PETScWrappers::MatrixBase::set | ( | const std::vector< unsigned int > & | indices, | |
const FullMatrix< PetscScalar > & | full_matrix, | |||
const bool | elide_zero_values = false | |||
) |
Set all elements given in a FullMatrix<double> into the sparse matrix locations given by indices
. In other words, this function writes the elements in full_matrix
into the 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.
If the present object (from a derived class of this one) happens to be a sparse matrix, then this function adds some new entries to the matrix if they didn't exist before, very much in contrast to the SparseMatrix class which throws an error if the entry does not exist.
The optional parameter elide_zero_values
can be used to specify whether zero values should be inserted anyway or they should be filtered away. The default value is false
, i.e., even zero values are inserted/replaced.
void PETScWrappers::MatrixBase::set | ( | const std::vector< unsigned int > & | row_indices, | |
const std::vector< unsigned int > & | col_indices, | |||
const FullMatrix< PetscScalar > & | full_matrix, | |||
const bool | elide_zero_values = false | |||
) |
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.
void PETScWrappers::MatrixBase::set | ( | const unsigned int | row, | |
const std::vector< unsigned int > & | col_indices, | |||
const std::vector< PetscScalar > & | values, | |||
const bool | elide_zero_values = false | |||
) |
Set several elements in the specified row of the matrix with column indices as given by col_indices
to the respective value.
If the present object (from a derived class of this one) happens to be a sparse matrix, then this function adds some new entries to the matrix if they didn't exist before, very much in contrast to the SparseMatrix class which throws an error if the entry does not exist.
The optional parameter elide_zero_values
can be used to specify whether zero values should be inserted anyway or they should be filtered away. The default value is false
, i.e., even zero values are inserted/replaced.
void PETScWrappers::MatrixBase::set | ( | const unsigned int | row, | |
const unsigned int | n_cols, | |||
const unsigned int * | col_indices, | |||
const PetscScalar * | values, | |||
const bool | elide_zero_values = false | |||
) |
Set several elements to values given by values
in a given row in columns given by col_indices into the sparse matrix.
If the present object (from a derived class of this one) happens to be a sparse matrix, then this function adds some new entries to the matrix if they didn't exist before, very much in contrast to the SparseMatrix class which throws an error if the entry does not exist.
The optional parameter elide_zero_values
can be used to specify whether zero values should be inserted anyway or they should be filtered away. The default value is false
, i.e., even zero values are inserted/replaced.
void PETScWrappers::MatrixBase::add | ( | const unsigned int | i, | |
const unsigned int | j, | |||
const PetscScalar | value | |||
) |
Add value
to the element (i,j).
If the present object (from a derived class of this one) happens to be a sparse matrix, then this function adds a new entry to the matrix if it didn't exist before, very much in contrast to the SparseMatrix class which throws an error if the entry does not exist. If value
is not a finite number an exception is thrown.
void PETScWrappers::MatrixBase::add | ( | const std::vector< unsigned int > & | indices, | |
const FullMatrix< PetscScalar > & | 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.
If the present object (from a derived class of this one) happens to be a sparse matrix, then this function adds some new entries to the matrix if they didn't exist before, very much in contrast to the SparseMatrix class which throws an error if the entry does not exist.
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.
void PETScWrappers::MatrixBase::add | ( | const std::vector< unsigned int > & | row_indices, | |
const std::vector< unsigned int > & | col_indices, | |||
const FullMatrix< PetscScalar > & | 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.
void PETScWrappers::MatrixBase::add | ( | const unsigned int | row, | |
const std::vector< unsigned int > & | col_indices, | |||
const std::vector< PetscScalar > & | 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.
If the present object (from a derived class of this one) happens to be a sparse matrix, then this function adds some new entries to the matrix if they didn't exist before, very much in contrast to the SparseMatrix class which throws an error if the entry does not exist.
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.
void PETScWrappers::MatrixBase::add | ( | const unsigned int | row, | |
const unsigned int | n_cols, | |||
const unsigned int * | col_indices, | |||
const PetscScalar * | 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.
If the present object (from a derived class of this one) happens to be a sparse matrix, then this function adds some new entries to the matrix if they didn't exist before, very much in contrast to the SparseMatrix class which throws an error if the entry does not exist.
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.
void PETScWrappers::MatrixBase::clear_row | ( | const unsigned int | row, | |
const PetscScalar | new_diag_value = 0 | |||
) |
Remove all elements from this row
by setting them to zero. The function does not modify the number of allocated nonzero entries, it only sets some entries to zero. It may drop them from the sparsity pattern, though (but retains the allocated memory in case new entries are again added later).
This operation is used in eliminating constraints (e.g. due to hanging nodes) and makes sure that we can write this modification to the matrix without having to read entries (such as the locations of non-zero elements) from it -- without this operation, removing constraints on parallel matrices is a rather complicated procedure.
The second parameter can be used to set the diagonal entry of this row to a value different from zero. The default is to set it to zero.
void PETScWrappers::MatrixBase::clear_rows | ( | const std::vector< unsigned int > & | rows, | |
const PetscScalar | new_diag_value = 0 | |||
) |
Same as clear_row(), except that it works on a number of rows at once.
The second parameter can be used to set the diagonal entries of all cleared rows to something different from zero. Note that all of these diagonal entries get the same value -- if you want different values for the diagonal entries, you have to set them by hand.
void PETScWrappers::MatrixBase::compress | ( | ) |
PETSc matrices store their own sparsity patterns. So, in analogy to our own SparsityPattern class, this function compresses the sparsity pattern and allows the resulting matrix to be used in all other operations where before only assembly functions were allowed. This function must therefore be called once you have assembled the matrix.
PetscScalar PETScWrappers::MatrixBase::operator() | ( | const unsigned int | i, | |
const unsigned int | j | |||
) | const |
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 contrast to the respective function in the MatrixBase
class, we don't throw an exception if the respective entry doesn't exist in the sparsity pattern of this class, since PETSc does not transmit this information.
This function is therefore exactly equivalent to the el()
function.
Return the value of the matrix entry (i,j). If this entry does not exist in the sparsity pattern, then zero is returned. While this may be convenient in some cases, note that it is simple to write algorithms that are slow compared to an optimal solution, since the sparsity of the matrix is not used.
Return the main diagonal element in the ith row. This function throws an error if the matrix is not quadratic.
Since we do not have direct access to the underlying data structure, this function is no faster than the elementwise access using the el() function. However, we provide this function for compatibility with the SparseMatrix class.
Return the local dimension of the matrix, i.e. the number of rows stored on the present MPI process. For sequential matrices, this number is the same as m(), but for parallel matrices it may be smaller.
To figure out which elements exactly are stored locally, use local_range().
Return a pair of indices indicating which rows of this matrix are stored locally. The first number is the index of the first row stored, the second the index of the one past the last one that is stored locally. If this is a sequential matrix, then the result will be the pair (0,m()), otherwise it will be a pair (i,i+n), where n=local_size()
.
Return whether index
is in the local range or not, see also local_range().
virtual const MPI_Comm& PETScWrappers::MatrixBase::get_mpi_communicator | ( | ) | const [pure virtual] |
Return a reference to the MPI communicator object in use with this matrix. This function has to be implemented in derived classes.
Implemented in PETScWrappers::FullMatrix, PETScWrappers::MPI::SparseMatrix, and PETScWrappers::SparseMatrix.
Return the number of nonzero elements of this matrix. Actually, it returns the number of entries in the sparsity pattern; if any of the entries should happen to be zero, it is counted anyway.
Number of entries in a specific row.
PetscReal PETScWrappers::MatrixBase::l1_norm | ( | ) | const |
Return the l1-norm of the matrix, that is , (max. sum of columns). This is the natural matrix norm that is compatible to the l1-norm for vectors, i.e.
. (cf. Haemmerlin-Hoffmann: Numerische Mathematik)
PetscReal PETScWrappers::MatrixBase::linfty_norm | ( | ) | const |
Return the linfty-norm of the matrix, that is , (max. sum of rows). This is the natural matrix norm that is compatible to the linfty-norm of vectors, i.e.
. (cf. Haemmerlin-Hoffmann: Numerische Mathematik)
PetscReal PETScWrappers::MatrixBase::frobenius_norm | ( | ) | const |
Return the frobenius norm of the matrix, i.e. the square root of the sum of squares of all entries in the matrix.
MatrixBase& PETScWrappers::MatrixBase::operator*= | ( | const PetscScalar | factor | ) |
Multiply the entire matrix by a fixed factor.
MatrixBase& PETScWrappers::MatrixBase::operator/= | ( | const PetscScalar | factor | ) |
Divide the entire matrix by a fixed factor.
void PETScWrappers::MatrixBase::vmult | ( | VectorBase & | dst, | |
const VectorBase & | src | |||
) | const |
Matrix-vector multiplication: let dst = M*src with M being this matrix.
Source and destination must not be the same vector.
Note that if the current object represents a parallel distributed matrix (of type PETScWrappers::MPI::SparseMatrix), then both vectors have to be distributed vectors as well. Conversely, if the matrix is not distributed, then neither of the vectors may be.
void PETScWrappers::MatrixBase::Tvmult | ( | VectorBase & | dst, | |
const VectorBase & | src | |||
) | const |
Matrix-vector multiplication: let dst = MT*src with M being this matrix. This function does the same as vmult() but takes the transposed matrix.
Source and destination must not be the same vector.
Note that if the current object represents a parallel distributed matrix (of type PETScWrappers::MPI::SparseMatrix), then both vectors have to be distributed vectors as well. Conversely, if the matrix is not distributed, then neither of the vectors may be.
void PETScWrappers::MatrixBase::vmult_add | ( | VectorBase & | dst, | |
const VectorBase & | src | |||
) | const |
Adding Matrix-vector multiplication. Add M*src on dst with M being this matrix.
Source and destination must not be the same vector.
Note that if the current object represents a parallel distributed matrix (of type PETScWrappers::MPI::SparseMatrix), then both vectors have to be distributed vectors as well. Conversely, if the matrix is not distributed, then neither of the vectors may be.
void PETScWrappers::MatrixBase::Tvmult_add | ( | VectorBase & | dst, | |
const VectorBase & | src | |||
) | const |
Adding Matrix-vector multiplication. Add MT*src to dst with M being this matrix. This function does the same as vmult_add() but takes the transposed matrix.
Source and destination must not be the same vector.
Note that if the current object represents a parallel distributed matrix (of type PETScWrappers::MPI::SparseMatrix), then both vectors have to be distributed vectors as well. Conversely, if the matrix is not distributed, then neither of the vectors may be.
PetscScalar PETScWrappers::MatrixBase::matrix_norm_square | ( | const VectorBase & | v | ) | const |
Return the square of the norm of the vector with respect to the norm induced by this matrix, i.e.
. This is useful, e.g. in the finite element context, where the
norm of a function equals the matrix norm with respect to the mass matrix of the vector representing the nodal values of the finite element function.
Obviously, the matrix needs to be quadratic for this operation.
The implementation of this function is not as efficient as the one in the MatrixBase
class used in deal.II (i.e. the original one, not the PETSc wrapper class) since PETSc doesn't support this operation and needs a temporary vector.
Note that if the current object represents a parallel distributed matrix (of type PETScWrappers::MPI::SparseMatrix), then the given vector has to be a distributed vector as well. Conversely, if the matrix is not distributed, then neither may the vector be.
PetscScalar PETScWrappers::MatrixBase::matrix_scalar_product | ( | const VectorBase & | u, | |
const VectorBase & | v | |||
) | const |
Compute the matrix scalar product .
The implementation of this function is not as efficient as the one in the MatrixBase
class used in deal.II (i.e. the original one, not the PETSc wrapper class) since PETSc doesn't support this operation and needs a temporary vector.
Note that if the current object represents a parallel distributed matrix (of type PETScWrappers::MPI::SparseMatrix), then both vectors have to be distributed vectors as well. Conversely, if the matrix is not distributed, then neither of the vectors may be.
PetscScalar PETScWrappers::MatrixBase::residual | ( | VectorBase & | dst, | |
const VectorBase & | x, | |||
const VectorBase & | b | |||
) | const |
Compute the residual of an equation Mx=b, where the residual is defined to be r=b-Mx. Write the residual into dst
. The l2 norm of the residual vector is returned.
Source x and destination dst must not be the same vector.
Note that if the current object represents a parallel distributed matrix (of type PETScWrappers::MPI::SparseMatrix), then all vectors have to be distributed vectors as well. Conversely, if the matrix is not distributed, then neither of the vectors may be.
const_iterator PETScWrappers::MatrixBase::begin | ( | ) | const |
STL-like iterator with the first entry.
const_iterator PETScWrappers::MatrixBase::end | ( | ) | const |
Final iterator.
const_iterator PETScWrappers::MatrixBase::begin | ( | const unsigned int | r | ) | const |
STL-like iterator with the first entry of row r
.
Note that if the given row is empty, i.e. does not contain any nonzero entries, then the iterator returned by this function equals end(r)
. Note also that the iterator may not be dereferencable in that case.
const_iterator PETScWrappers::MatrixBase::end | ( | const unsigned int | r | ) | const |
Final iterator of row r
. It points to the first element past the end of line r
, or past the end of the entire sparsity pattern.
Note that the end iterator is not necessarily dereferencable. This is in particular the case if it is the end iterator for the last row of a matrix.
PETScWrappers::MatrixBase::operator const Mat | ( | ) | const |
Conversion operator to gain access to the underlying PETSc type. If you do this, you cut this class off some information it may need, so this conversion operator should only be used if you know what you do. In particular, it should only be used for read-only operations into the matrix.
void PETScWrappers::MatrixBase::transpose | ( | ) |
Make an in-place transpose of a matrix.
PetscTruth PETScWrappers::MatrixBase::is_symmetric | ( | const double | tol = 0.0 |
) |
Test whether a matrix is symmetric. Default tolerance is zero.
PetscTruth PETScWrappers::MatrixBase::is_hermitian | ( | const double | tol = 0.0 |
) |
Test whether a matrix is Hermitian, i.e. it is the complex conjugate of its transpose. Default tolerance is zero.
void PETScWrappers::MatrixBase::write_ascii | ( | ) |
Mat PETScWrappers::MatrixBase::matrix [protected] |
A generic matrix object in PETSc. The actual type, a sparse matrix, is set in the constructor.
Store whether the last action was a write or add operation.
std::vector<unsigned int> PETScWrappers::MatrixBase::column_indices [private] |
An internal array of integer values that is used to store the column indices when adding/inserting local data into the (large) sparse matrix.
std::vector<PetscScalar> PETScWrappers::MatrixBase::column_values [private] |
An internal array of double values that is used to store the column indices when adding/inserting local data into the (large) sparse matrix.