Classes | |
class | AdditionalData |
class | ExcInvalidStrengthening |
Public Member Functions | |
virtual | ~SparseLUDecomposition () |
virtual void | clear () |
template<typename somenumber > | |
void | initialize (const SparseMatrix< somenumber > &matrix, const AdditionalData parameters) |
void | reinit (const SparsityPattern &sparsity) |
template<typename somenumber > | |
void | decompose (const SparseMatrix< somenumber > &matrix, const double strengthen_diagonal=0.) |
virtual bool | is_decomposed () const |
bool | empty () const |
virtual unsigned int | memory_consumption () const |
Protected Member Functions | |
SparseLUDecomposition () | |
SparseLUDecomposition (const SparsityPattern &sparsity) | |
template<typename somenumber > | |
void | copy_from (const SparseMatrix< somenumber > &matrix) |
virtual void | strengthen_diagonal_impl () |
virtual number | get_strengthen_diagonal (const number rowsum, const unsigned int row) const |
Protected Attributes | |
bool | decomposed |
double | strengthen_diagonal |
std::vector< const unsigned int * > | prebuilt_lower_bound |
Private Member Functions | |
void | prebuild_lower_bound () |
Private Attributes | |
SparsityPattern * | own_sparsity |
Abstract base class for sparse LU decompositions of a sparse matrix into another sparse matrix. 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 two different matrix factors), the derivation is protected
rather than public
.
The sparse LU 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 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 a copy-constructor of the SparsityPattern class which allows the addition of side-diagonals to a given sparsity structure.
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:
SparseILU<double> ilu; ilu.initialize(matrix, SparseILU<double>::AdditionalData(...)); somesolver.solve (A, x, f, ilu);
Through the AdditionalData object it is possible to specify additional parameters of the LU decomposition.
1/ The matrix diagonals 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).
The state management simply requires the initialize() function to be called before the object is used as preconditioner.
Obsolete: In order to prevent users from applying decompositions before the decomposition itself has been built, and to introduce some optimization of common "sparse idioms", this class introduces a simple state management. A SparseLUdecomposition instance is considered not decomposed if the decompose method has not yet been invoked since the last time the underlying SparseMatrix had changed. The underlying sparse matrix is considered changed when one of this class reinit methods, constructors or destructors are invoked. The not-decomposed state is indicated by a false value returned by is_decomposed() method. It is illegal to apply this decomposition (vmult() method) in not decomposed state; in this case, the vmult() method throws an ExcInvalidState
exception. This object turns into decomposed state immediately after its decompose() method is invoked. The decomposed state is indicated by true value returned by is_decomposed() method. It is legal to apply this decomposition (vmult() method) in decomposed state.
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. You should invoke the non-abstract base class method to employ the state management. Implementations may choose more restrictive definition of what is legal or illegal state; but they must conform to the is_decomposed() method specification above.
If an exception is thrown by method other than vmult(), this object may be left in an inconsistent state.
SparseLUDecomposition< number >::SparseLUDecomposition | ( | ) | [protected] |
Constructor. Does nothing.
Call the initialize() function before using this object as preconditioner (vmult()).
SparseLUDecomposition< number >::SparseLUDecomposition | ( | const SparsityPattern & | sparsity | ) | [protected] |
This method is deprecated, and left for backward compability. It will be removed in later versions.
virtual SparseLUDecomposition< number >::~SparseLUDecomposition | ( | ) | [virtual] |
Destruction. Mark the destructor pure to ensure that this class isn't used directly, but only its derived classes.
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 >.
void SparseLUDecomposition< number >::initialize | ( | const SparseMatrix< somenumber > & | matrix, | |
const AdditionalData | parameters | |||
) | [inline] |
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).
Reimplemented in SparseILU< number >, and SparseMIC< number >.
void SparseLUDecomposition< number >::reinit | ( | const SparsityPattern & | sparsity | ) | [virtual] |
This method is deprecated, and left for backward compatibility. It will be removed in later versions.
Reimplemented from SparseMatrix< number >.
Reimplemented in SparseMIC< number >.
void SparseLUDecomposition< number >::decompose | ( | const SparseMatrix< somenumber > & | matrix, | |
const double | strengthen_diagonal = 0. | |||
) | [inline] |
This method is deprecated, and left for backward compability. It will be removed in later versions.
Reimplemented in SparseILU< number >, and SparseMIC< number >.
virtual bool SparseLUDecomposition< number >::is_decomposed | ( | ) | const [virtual] |
This method is deprecated, and left for backward compability. It will be removed in later versions.
bool SparseLUDecomposition< number >::empty | ( | ) | const |
Return whether the object is empty. It calls the inherited SparseMatrix::empty() function.
Reimplemented from SparseMatrix< number >.
virtual unsigned int SparseLUDecomposition< number >::memory_consumption | ( | ) | const [virtual] |
Determine an estimate for the memory consumption (in bytes) of this object.
Reimplemented from SparseMatrix< number >.
Reimplemented in SparseILU< number >, and SparseMIC< number >.
void SparseLUDecomposition< number >::copy_from | ( | const SparseMatrix< somenumber > & | matrix | ) | [inline, protected] |
Copies the passed SparseMatrix onto this object. This object's sparsity pattern remains unchanged.
virtual void SparseLUDecomposition< number >::strengthen_diagonal_impl | ( | ) | [protected, virtual] |
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
.
virtual number SparseLUDecomposition< number >::get_strengthen_diagonal | ( | const number | rowsum, | |
const unsigned int | row | |||
) | const [protected, virtual] |
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.
void SparseLUDecomposition< number >::prebuild_lower_bound | ( | ) | [private] |
Fills the prebuilt_lower_bound array.
bool SparseLUDecomposition< number >::decomposed [protected] |
State flag. If not in decomposed state, it is illegal to apply the decomposition. This flag is cleared when the underlaying SparseMatrix SparsityPattern is changed, and set by decompose().
double SparseLUDecomposition< number >::strengthen_diagonal [protected] |
The default strenghtening value, returned by get_strengthen_diagonal().
std::vector<const unsigned int*> 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().
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.