From 437de341ad013593a355514da41f64fe62007d20 Mon Sep 17 00:00:00 2001 From: bangerth Date: Fri, 18 Jan 2013 00:47:05 +0000 Subject: [PATCH] Update documentation in a number of places and make a parameter a reference. git-svn-id: https://svn.dealii.org/trunk@28113 0785d39b-7218-0410-832d-ea1e28bc413d --- .../deal.II/lac/sparse_decomposition.h | 17 ++--- deal.II/include/deal.II/lac/sparse_ilu.h | 25 ++++---- .../deal.II/lac/sparse_ilu.templates.h | 2 +- deal.II/include/deal.II/lac/sparse_mic.h | 62 ++++++++++++++----- .../deal.II/lac/sparse_mic.templates.h | 2 +- 5 files changed, 72 insertions(+), 36 deletions(-) diff --git a/deal.II/include/deal.II/lac/sparse_decomposition.h b/deal.II/include/deal.II/lac/sparse_decomposition.h index 17e25c9bd7..3f3d9cf42a 100644 --- a/deal.II/include/deal.II/lac/sparse_decomposition.h +++ b/deal.II/include/deal.II/lac/sparse_decomposition.h @@ -25,8 +25,8 @@ DEAL_II_NAMESPACE_OPEN */ /** - * 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. * @@ -39,10 +39,11 @@ DEAL_II_NAMESPACE_OPEN * *

Fill-in

* - * 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. @@ -148,10 +149,12 @@ protected: 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; diff --git a/deal.II/include/deal.II/lac/sparse_ilu.h b/deal.II/include/deal.II/lac/sparse_ilu.h index 900c857232..8ad744ede8 100644 --- a/deal.II/include/deal.II/lac/sparse_ilu.h +++ b/deal.II/include/deal.II/lac/sparse_ilu.h @@ -25,11 +25,12 @@ DEAL_II_NAMESPACE_OPEN */ /** - * 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 @@ -62,10 +63,12 @@ public: 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; @@ -112,10 +115,10 @@ public: */ template void initialize (const SparseMatrix &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. diff --git a/deal.II/include/deal.II/lac/sparse_ilu.templates.h b/deal.II/include/deal.II/lac/sparse_ilu.templates.h index ff2ea3df13..6bb71fa990 100644 --- a/deal.II/include/deal.II/lac/sparse_ilu.templates.h +++ b/deal.II/include/deal.II/lac/sparse_ilu.templates.h @@ -40,7 +40,7 @@ SparseILU::SparseILU (const SparsityPattern &sparsity) : template template void SparseILU::initialize (const SparseMatrix &matrix, - const AdditionalData data) + const AdditionalData &data) { SparseLUDecomposition::initialize(matrix, data); diff --git a/deal.II/include/deal.II/lac/sparse_mic.h b/deal.II/include/deal.II/lac/sparse_mic.h index f4ba0fbc2b..b250b3fb45 100644 --- a/deal.II/include/deal.II/lac/sparse_mic.h +++ b/deal.II/include/deal.II/lac/sparse_mic.h @@ -28,11 +28,11 @@ DEAL_II_NAMESPACE_OPEN * *

The decomposition

* - * 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. @@ -43,21 +43,23 @@ class SparseMIC : public SparseLUDecomposition 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(); @@ -88,17 +90,45 @@ public: 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 void initialize (const SparseMatrix &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 void decompose (const SparseMatrix &matrix, diff --git a/deal.II/include/deal.II/lac/sparse_mic.templates.h b/deal.II/include/deal.II/lac/sparse_mic.templates.h index 4cf41a9c6b..9d9c98ff92 100644 --- a/deal.II/include/deal.II/lac/sparse_mic.templates.h +++ b/deal.II/include/deal.II/lac/sparse_mic.templates.h @@ -72,7 +72,7 @@ template template inline void SparseMIC::initialize (const SparseMatrix &matrix, - const AdditionalData data) + const AdditionalData &data) { SparseLUDecomposition::initialize(matrix, data); -- 2.39.5