Reference documentation for deal.II version Git 8e6d603 2015-07-02 09:40:47 +0200
Classes | Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | Private Attributes | List of all members
SparseLUDecomposition< number > Class Template Referenceabstract

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

Inheritance diagram for SparseLUDecomposition< number >:
[legend]

Classes

class  AdditionalData
 

Public Types

typedef types::global_dof_index size_type
 

Public Member Functions

virtual ~SparseLUDecomposition ()=0
 
virtual void clear ()
 
template<typename somenumber >
void initialize (const SparseMatrix< somenumber > &matrix, const AdditionalData parameters)
 
bool empty () const
 
virtual std::size_t memory_consumption () const
 
 DeclException1 (ExcInvalidStrengthening, double,<< "The strengthening parameter "<< arg1<< " is not greater or equal than zero!")
 
- Public Member Functions inherited from Subscriptor
 Subscriptor ()
 
 Subscriptor (const Subscriptor &)
 
virtual ~Subscriptor ()
 
Subscriptoroperator= (const Subscriptor &)
 
void subscribe (const char *identifier=0) const
 
void unsubscribe (const char *identifier=0) const
 
unsigned int n_subscriptions () const
 
void list_subscribers () const
 
 DeclException3 (ExcInUse, int, char *, std::string &,<< "Object of class "<< arg2<< " is still used by "<< arg1<< " other objects."<< "\n\n"<< "(Additional information: "<< arg3<< ")\n\n"<< "See the entry in the Frequently Asked Questions of "<< "deal.II (linked to from http://www.dealii.org/) for "<< "a lot more information on what this error means and "<< "how to fix programs in which it happens.")
 
 DeclException2 (ExcNoSubscriber, char *, char *,<< "No subscriber with identifier <"<< arg2<< "> subscribes to this object of class "<< arg1<< ". Consequently, it cannot be unsubscribed.")
 
template<class Archive >
void serialize (Archive &ar, const unsigned int version)
 

Protected Member Functions

 SparseLUDecomposition ()
 
template<typename somenumber >
void copy_from (const SparseMatrix< somenumber > &matrix)
 
virtual void strengthen_diagonal_impl ()
 
virtual number get_strengthen_diagonal (const number rowsum, const size_type row) const
 
void prebuild_lower_bound ()
 
- Protected Member Functions inherited from SparseMatrix< number >
void prepare_add ()
 
void prepare_set ()
 
 DeclException2 (ExcInvalidIndex, int, int,<< "The entry with index <"<< arg1<< ','<< arg2<< "> does not exist.")
 
 DeclException1 (ExcInvalidIndex1, int,<< "The index "<< arg1<< " is not in the allowed range.")
 
 DeclException0 (ExcDifferentSparsityPatterns)
 
 DeclException2 (ExcIteratorRange, int, int,<< "The iterators denote a range of "<< arg1<< " elements, but the given number of rows was "<< arg2)
 
 DeclException0 (ExcSourceEqualsDestination)
 
 SparseMatrix ()
 
 SparseMatrix (const SparseMatrix &)
 
 SparseMatrix (const SparsityPattern &sparsity)
 
 SparseMatrix (const SparsityPattern &sparsity, const IdentityMatrix &id)
 
virtual ~SparseMatrix ()
 
SparseMatrix< number > & operator= (const SparseMatrix< number > &)
 
SparseMatrix< number > & operator= (const IdentityMatrix &id)
 
SparseMatrixoperator= (const double d)
 
virtual void reinit (const SparsityPattern &sparsity)
 
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
 
size_type n_actually_nonzero_elements (const double threshold=0.) const
 
const SparsityPatternget_sparsity_pattern () const
 
std::size_t memory_consumption () const
 
void compress (::VectorOperation::values)
 
void set (const size_type i, const size_type j, const number value)
 
template<typename number2 >
void set (const std::vector< size_type > &indices, const FullMatrix< number2 > &full_matrix, const bool elide_zero_values=false)
 
template<typename number2 >
void set (const std::vector< size_type > &row_indices, const std::vector< size_type > &col_indices, const FullMatrix< number2 > &full_matrix, const bool elide_zero_values=false)
 
template<typename number2 >
void set (const size_type row, const std::vector< size_type > &col_indices, const std::vector< number2 > &values, const bool elide_zero_values=false)
 
template<typename number2 >
void set (const size_type row, const size_type n_cols, const size_type *col_indices, const number2 *values, const bool elide_zero_values=false)
 
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)
 
SparseMatrixoperator*= (const number factor)
 
SparseMatrixoperator/= (const number factor)
 
void symmetrize ()
 
template<typename somenumber >
SparseMatrix< number > & copy_from (const SparseMatrix< somenumber > &source)
 
template<typename ForwardIterator >
void copy_from (const ForwardIterator begin, const ForwardIterator end)
 
template<typename somenumber >
void copy_from (const FullMatrix< somenumber > &matrix)
 
SparseMatrix< number > & copy_from (const TrilinosWrappers::SparseMatrix &matrix)
 
template<typename somenumber >
void add (const number factor, const SparseMatrix< somenumber > &matrix)
 
number operator() (const size_type i, const size_type j) const
 
number el (const size_type i, const size_type j) const
 
number diag_element (const size_type i) const
 
number & diag_element (const size_type i)
 
template<class OutVector , class InVector >
void vmult (OutVector &dst, const InVector &src) const
 
template<class OutVector , class InVector >
void Tvmult (OutVector &dst, const InVector &src) const
 
template<class OutVector , class InVector >
void vmult_add (OutVector &dst, const InVector &src) const
 
template<class OutVector , class InVector >
void Tvmult_add (OutVector &dst, const InVector &src) const
 
template<typename somenumber >
somenumber matrix_norm_square (const Vector< somenumber > &v) const
 
template<typename somenumber >
somenumber matrix_scalar_product (const Vector< somenumber > &u, const Vector< somenumber > &v) const
 
template<typename somenumber >
somenumber residual (Vector< somenumber > &dst, const Vector< somenumber > &x, const Vector< somenumber > &b) const
 
template<typename numberB , typename numberC >
void mmult (SparseMatrix< numberC > &C, const SparseMatrix< numberB > &B, const Vector< number > &V=Vector< number >(), const bool rebuild_sparsity_pattern=true) const
 
template<typename numberB , typename numberC >
void Tmmult (SparseMatrix< numberC > &C, const SparseMatrix< numberB > &B, const Vector< number > &V=Vector< number >(), const bool rebuild_sparsity_pattern=true) const
 
real_type l1_norm () const
 
real_type linfty_norm () const
 
real_type frobenius_norm () const
 
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 omega=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 somenumber >
void SSOR (Vector< somenumber > &v, const number omega=1.) const
 
template<typename somenumber >
void SOR (Vector< somenumber > &v, const number om=1.) const
 
template<typename somenumber >
void TSOR (Vector< somenumber > &v, const number om=1.) const
 
template<typename somenumber >
void PSOR (Vector< somenumber > &v, const std::vector< size_type > &permutation, const std::vector< size_type > &inverse_permutation, const number om=1.) const
 
template<typename somenumber >
void TPSOR (Vector< somenumber > &v, const std::vector< size_type > &permutation, const std::vector< size_type > &inverse_permutation, const number om=1.) const
 
template<typename somenumber >
void Jacobi_step (Vector< somenumber > &v, const Vector< somenumber > &b, const number om=1.) const
 
template<typename somenumber >
void SOR_step (Vector< somenumber > &v, const Vector< somenumber > &b, const number om=1.) const
 
template<typename somenumber >
void TSOR_step (Vector< somenumber > &v, const Vector< somenumber > &b, const number om=1.) const
 
template<typename somenumber >
void SSOR_step (Vector< somenumber > &v, const Vector< somenumber > &b, const number om=1.) const
 
const_iterator begin () const
 
iterator begin ()
 
const_iterator end () const
 
iterator end ()
 
const_iterator begin (const size_type r) const
 
iterator begin (const size_type r)
 
const_iterator end (const size_type r) const
 
iterator end (const size_type r)
 
template<class STREAM >
void print (STREAM &out, const bool across=false, const bool diagonal_first=true) 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 print_pattern (std::ostream &out, const double threshold=0.) const
 
void block_write (std::ostream &out) const
 
void block_read (std::istream &in)
 
- Protected Member Functions inherited from Subscriptor
 Subscriptor ()
 
 Subscriptor (const Subscriptor &)
 
virtual ~Subscriptor ()
 
Subscriptoroperator= (const Subscriptor &)
 
void subscribe (const char *identifier=0) const
 
void unsubscribe (const char *identifier=0) const
 
unsigned int n_subscriptions () const
 
void list_subscribers () const
 
 DeclException3 (ExcInUse, int, char *, std::string &,<< "Object of class "<< arg2<< " is still used by "<< arg1<< " other objects."<< "\n\n"<< "(Additional information: "<< arg3<< ")\n\n"<< "See the entry in the Frequently Asked Questions of "<< "deal.II (linked to from http://www.dealii.org/) for "<< "a lot more information on what this error means and "<< "how to fix programs in which it happens.")
 
 DeclException2 (ExcNoSubscriber, char *, char *,<< "No subscriber with identifier <"<< arg2<< "> subscribes to this object of class "<< arg1<< ". Consequently, it cannot be unsubscribed.")
 
template<class Archive >
void serialize (Archive &ar, const unsigned int version)
 

Protected Attributes

double strengthen_diagonal
 
std::vector< const size_type * > prebuilt_lower_bound
 

Private Attributes

SparsityPatternown_sparsity
 

Additional Inherited Members

- Protected Types inherited from SparseMatrix< number >
typedef types::global_dof_index size_type
 
typedef number value_type
 
typedef numbers::NumberTraits< number >::real_type real_type
 
typedef SparseMatrixIterators::Iterator< number, true > const_iterator
 
typedef SparseMatrixIterators::Iterator< number, false > iterator
 

Detailed Description

template<typename number>
class SparseLUDecomposition< number >

Abstract base class for incomplete decompositions of a sparse matrix into sparse factors. This class can't be used by itself, but only as the base class of derived classes that actually implement particular decompositions such as SparseILU or SparseMIC.

The decomposition is stored as a sparse matrix which is why this class is derived from the SparseMatrix. Since it is not a matrix in the usual sense (the stored entries are not those of a matrix, but of the two factors of the original matrix), the derivation is protected rather than public.

Fill-in

Sparse decompositions are frequently used with additional fill-in, i.e., the sparsity structure of the decomposition is denser than that of the matrix to be decomposed. The initialize() function of this class allows this fill-in via the AdditionalData object as long as all entries present in the original matrix are present in the decomposition also, i.e. the sparsity pattern of the decomposition is a superset of the sparsity pattern in the original matrix.

Such fill-in can be accomplished by various ways, one of which is the copy-constructor of the SparsityPattern class that allows the addition of side-diagonals to a given sparsity structure.

Unified use of preconditioners

While objects of this class can not be used directly (this class is only a base class for others implementing actual decompositions), derived classes such as SparseILU and SparseMIC can be used in the usual form as preconditioners. For example, this works:

somesolver.solve (A, x, f, ilu);

Through the AdditionalData object it is possible to specify additional parameters of the LU decomposition.

1/ The matrix diagonal can be strengthened by adding strengthen_diagonal times the sum of the absolute row entries of each row to the respective diagonal entries. By default no strengthening is performed.

2/ By default, each initialize() function call creates its own sparsity. For that, it copies the sparsity of matrix and adds a specific number of extra off diagonal entries specified by extra_off_diagonals.

3/ By setting use_previous_sparsity=true the sparsity is not recreated but the sparsity of the previous initialize() call is reused (recycled). This might be useful when several linear problems on the same sparsity need to solved, as for example several Newton iteration steps on the same triangulation. The default is false.

4/ It is possible to give a user defined sparsity to use_this_sparsity. Then, no sparsity is created but *use_this_sparsity is used to store the decomposed matrix. For restrictions on the sparsity see section `Fill-in' above).

Particular implementations

It is enough to override the initialize() and vmult() methods to implement particular LU decompositions, like the true LU, or the Cholesky decomposition. Additionally, if that decomposition needs fine tuned diagonal strengthening on a per row basis, it may override the get_strengthen_diagonal() method.

Author
Stephen "Cheffo" Kolaroff, 2002, based on SparseILU implementation by Wolfgang Bangerth; unified interface: Ralf Hartmann, 2003

Definition at line 108 of file sparse_decomposition.h.

Member Typedef Documentation

template<typename number >
typedef types::global_dof_index SparseLUDecomposition< number >::size_type

Declare type for container size.

Definition at line 124 of file sparse_decomposition.h.

Constructor & Destructor Documentation

template<typename number >
SparseLUDecomposition< number >::SparseLUDecomposition ( )
protected

Constructor. Does nothing.

Call the initialize() function before using this object as preconditioner (vmult()).

template<typename number >
virtual SparseLUDecomposition< number >::~SparseLUDecomposition ( )
pure virtual

Destruction. Mark the destructor pure to ensure that this class isn't used directly, but only its derived classes.

Member Function Documentation

template<typename number >
virtual void SparseLUDecomposition< number >::clear ( )
virtual

Deletes all member variables. Leaves the class in the state that it had directly after calling the constructor

Reimplemented from SparseMatrix< number >.

Reimplemented in SparseMIC< number >.

template<typename number >
template<typename somenumber >
void SparseLUDecomposition< number >::initialize ( const SparseMatrix< somenumber > &  matrix,
const AdditionalData  parameters 
)

This function needs to be called before an object of this class is used as preconditioner.

For more detail about possible parameters, see the class documentation and the documentation of the SparseLUDecomposition::AdditionalData class.

According to the parameters, this function creates a new SparsityPattern or keeps the previous sparsity or takes the sparsity given by the user to data. Then, this function performs the LU decomposition.

After this function is called the preconditioner is ready to be used (using the vmult function of derived classes).

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

Return whether the object is empty. It calls the inherited SparseMatrix::empty() function.

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

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

Reimplemented in SparseILU< number >, and SparseMIC< number >.

template<typename number >
template<typename somenumber >
void SparseLUDecomposition< number >::copy_from ( const SparseMatrix< somenumber > &  matrix)
protected

Copies the passed SparseMatrix onto this object. This object's sparsity pattern remains unchanged.

template<typename number >
virtual void SparseLUDecomposition< number >::strengthen_diagonal_impl ( )
protectedvirtual

Performs the strengthening loop. For each row calculates the sum of absolute values of its elements, determines the strengthening factor (through get_strengthen_diagonal()) sf and multiplies the diagonal entry with sf+1.

template<typename number >
virtual number SparseLUDecomposition< number >::get_strengthen_diagonal ( const number  rowsum,
const size_type  row 
) const
protectedvirtual

In the decomposition phase, computes a strengthening factor for the diagonal entry in row row with sum of absolute values of its elements rowsum.

Note
The default implementation in SparseLUDecomposition returns strengthen_diagonal's value.
template<typename number >
void SparseLUDecomposition< number >::prebuild_lower_bound ( )
protected

Fills the prebuilt_lower_bound array.

Member Data Documentation

template<typename number >
double SparseLUDecomposition< number >::strengthen_diagonal
protected

The default strengthening value, returned by get_strengthen_diagonal().

Definition at line 267 of file sparse_decomposition.h.

template<typename number >
std::vector<const size_type *> SparseLUDecomposition< number >::prebuilt_lower_bound
protected

For every row in the underlying SparsityPattern, this array contains a pointer to the row's first afterdiagonal entry. Becomes available after invocation of decompose().

Definition at line 274 of file sparse_decomposition.h.

template<typename number >
SparsityPattern* SparseLUDecomposition< number >::own_sparsity
private

In general this pointer is zero except for the case that no SparsityPattern is given to this class. Then, a SparsityPattern is created and is passed down to the SparseMatrix base class.

Nevertheless, the SparseLUDecomposition needs to keep ownership of this sparsity. It keeps this pointer to it enabling it to delete this sparsity at destruction time.

Definition at line 292 of file sparse_decomposition.h.


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