*/
/**
- * Abstract base class for sparse LU decompositions of a sparse matrix
- * into another sparse matrix. This class can't be used by itself, but
+ * 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.
*
*
* <h3>Fill-in</h3>
*
- * The sparse LU decompositions are frequently used with additional
- * fill-in, i.e. the sparsity structure of the decomposition is denser
+ * 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 as long as all entries
+ * 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.
SparseLUDecomposition ();
/**
- * This method is deprecated, and
+ * @deprecated This method is deprecated, and
* left for backward
- * compability. It will be removed
+ * compatibility. It will be removed
* in later versions.
+ * Instead, pass the sparsity pattern that you want used for
+ * the decomposition in the AdditionalData structure.
*/
SparseLUDecomposition (const SparsityPattern &sparsity) DEAL_II_DEPRECATED;
*/
/**
- * Incomplete LU decomposition of a sparse matrix into another sparse matrix.
- * A given matrix is decomposed into a incomplete LU factorization, where
- * by incomplete we mean that also a sparse decomposition is used and entries
- * in the decomposition that do not fit into the sparsity structure of this
- * object are discarded.
+ * This class computes an Incomplete LU (ILU) decomposition of a sparse matrix,
+ * using either the same sparsity pattern or a different one.
+ * By incomplete we mean that unlike the exact decomposition, the incomplete
+ * one is also computed using sparse factors, and entries
+ * in the decomposition that do not fit into the given sparsity structure
+ * are discarded.
*
* The algorithm used by this class is essentially a copy of the
* algorithm given in the book Y. Saad: "Iterative methods for sparse
SparseILU ();
/**
- * @deprecated This method is
- * deprecated, and left for
- * backward compability. It will
- * be removed in later versions.
+ * @deprecated This method is deprecated, and
+ * left for backward
+ * compatibility. It will be removed
+ * in later versions.
+ * Instead, pass the sparsity pattern that you want used for
+ * the decomposition in the AdditionalData structure.
*/
SparseILU (const SparsityPattern &sparsity) DEAL_II_DEPRECATED;
*/
template <typename somenumber>
void initialize (const SparseMatrix<somenumber> &matrix,
- const AdditionalData parameters = AdditionalData());
+ const AdditionalData ¶meters = AdditionalData());
/**
- * This method is deprecated, and
+ * @deprecate This method is deprecated, and
* left for backward
* compability. It will be
* removed in later versions.
template <typename number>
template <typename somenumber>
void SparseILU<number>::initialize (const SparseMatrix<somenumber> &matrix,
- const AdditionalData data)
+ const AdditionalData &data)
{
SparseLUDecomposition<number>::initialize(matrix, data);
*
* <h3>The decomposition</h3>
*
- * Let a sparse matrix A is in the form A = - L - U + D, where -L and
- * -U are strictly lower and upper triangular matrices. The MIC(0)
- * decomposition of the matrix A is defined by B = (X-L)X^(-1)(X-U),
- * where X is a diagonal matrix, defined by the condition rowsum(A) =
- * rowsum(B).
+ * Let a sparse matrix $A$ be in the form $A = - L - U + D$, where $-L$ and
+ * $-U$ are strictly lower and upper triangular matrices. The MIC(0)
+ * decomposition of the matrix $A$ is defined by $B = (X-L)X^(-1)(X-U)$,
+ * where $X$ is a diagonal matrix, defined by the condition $\text{rowsum}(A) =
+ * \text{rowsum}(B)$.
*
* @author Stephen "Cheffo" Kolaroff, 2002, unified interface: Ralf
* Hartmann 2003.
public:
/**
* Constructor. Does nothing, so
- * you have to call @p reinit
+ * you have to call @p decompose
* sometimes afterwards.
*/
SparseMIC ();
/**
- * Constructor. Initialize the
- * sparsity pattern of this
- * object with the given
- * argument.
+ * @deprecated This method is deprecated, and
+ * left for backward
+ * compatibility. It will be removed
+ * in later versions.
+ * Instead, pass the sparsity pattern that you want used for
+ * the decomposition in the AdditionalData structure.
*/
- SparseMIC (const SparsityPattern &sparsity);
+ SparseMIC (const SparsityPattern &sparsity) DEAL_II_DEPRECATED;
/**
- * Destruction.
+ * Destructor.
*/
virtual ~SparseMIC();
void reinit (const SparsityPattern &sparsity) DEAL_II_DEPRECATED;
/**
- * Same as @p decompose.
+ * Perform the incomplete LU
+ * factorization of the given
+ * matrix.
+ *
+ * This function needs to be
+ * called before an object of
+ * this class is used as
+ * preconditioner.
+ *
+ * For more details about
+ * possible parameters, see the
+ * class documentation of
+ * SparseLUDecomposition and the
+ * documentation of the
+ * @p SparseLUDecomposition::AdditionalData
+ * class.
+ *
+ * According to the
+ * @p parameters, this function
+ * creates a new SparsityPattern
+ * or keeps the previous sparsity
+ * or takes the sparsity given by
+ * the user to @p data. Then,
+ * this function performs the MIC
+ * decomposition.
+ *
+ * After this function is called
+ * the preconditioner is ready to
+ * be used.
*/
template <typename somenumber>
void initialize (const SparseMatrix<somenumber> &matrix,
- const AdditionalData parameters);
+ const AdditionalData ¶meters = AdditionalData());
/**
- * This method is deprecated, and
+ * @deprecate This method is deprecated, and
* left for backward
* compability. It will be
- * removed in later versions.
+ * removed in later versions. Use initialize() instead.
*/
template <typename somenumber>
void decompose (const SparseMatrix<somenumber> &matrix,
template <typename somenumber>
inline
void SparseMIC<number>::initialize (const SparseMatrix<somenumber> &matrix,
- const AdditionalData data)
+ const AdditionalData &data)
{
SparseLUDecomposition<number>::initialize(matrix, data);