From d7f70a5c6a3a68e657c2f2c4ef936fb4f37b6450 Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Tue, 24 Feb 2015 07:37:42 -0600 Subject: [PATCH] Update documentation. --- include/deal.II/lac/sparse_decomposition.h | 86 ++++++++-------------- 1 file changed, 30 insertions(+), 56 deletions(-) diff --git a/include/deal.II/lac/sparse_decomposition.h b/include/deal.II/lac/sparse_decomposition.h index 9ae6d10299..c6f3ac6a31 100644 --- a/include/deal.II/lac/sparse_decomposition.h +++ b/include/deal.II/lac/sparse_decomposition.h @@ -35,8 +35,9 @@ DEAL_II_NAMESPACE_OPEN * * 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 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

@@ -49,9 +50,9 @@ DEAL_II_NAMESPACE_OPEN * 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. + * 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

@@ -70,62 +71,35 @@ DEAL_II_NAMESPACE_OPEN * 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 + * 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 + * For that, it copies the sparsity of matrix and adds a specific * number of extra off diagonal entries specified by - * extra_off_diagonals. + * extra_off_diagonals. * - * 3/ By setting use_previous_sparsity=true the sparsity is not + * 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. + * 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 + * 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). * * - *

State management

- * - * 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. - * *

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. 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. + * get_strengthen_diagonal() method. * * @author Stephen "Cheffo" Kolaroff, 2002, based on SparseILU implementation * by Wolfgang Bangerth; unified interface: Ralf Hartmann, 2003 @@ -176,7 +150,7 @@ public: const SparsityPattern *use_this_sparsity=0); /** - * strengthen_diag times the sum of absolute row entries is added + * strengthen_diag times the sum of absolute row entries is added * to the diagonal entries. * * Per default, this value is zero, i.e. the diagonal is not strengthened. @@ -184,13 +158,13 @@ public: double strengthen_diagonal; /** - * By default, the initialize(matrix, data) function creates its + * By default, the initialize(matrix, data) function creates its * own sparsity. This sparsity has the same SparsityPattern as - * matrix with some extra off diagonals the number of which is - * specified by extra_off_diagonals. + * matrix with some extra off diagonals the number of which is + * specified by extra_off_diagonals. * - * The user can give a SparsityPattern to use_this_sparsity. Then - * this sparsity is used and the extra_off_diagonals argument is + * The user can give a SparsityPattern to use_this_sparsity. Then + * this sparsity is used and the extra_off_diagonals argument is * ignored. */ unsigned int extra_off_diagonals; @@ -207,10 +181,10 @@ public: /** * When a SparsityPattern is given to this argument, the initialize() - * function calls reinit(*use_this_sparsity) causing this + * function calls reinit(*use_this_sparsity) causing this * sparsity to be used. * - * Note that the sparsity structures of *use_this_sparsity and + * Note that the sparsity structures of *use_this_sparsity and * the matrix passed to the initialize function need not be equal. Fill-in * is allowed, as well as filtering out some elements in the matrix. */ @@ -224,9 +198,9 @@ public: * 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 + * 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 + * 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 @@ -273,17 +247,17 @@ protected: * 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. + * with sf+1. */ virtual void strengthen_diagonal_impl (); /** * In the decomposition phase, computes a strengthening factor for the - * diagonal entry in row row with sum of absolute values of its - * elements rowsum. + * 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. + * strengthen_diagonal's value. */ virtual number get_strengthen_diagonal(const number rowsum, const size_type row) const; @@ -303,7 +277,7 @@ protected: * Fills the #prebuilt_lower_bound array. */ void prebuild_lower_bound (); - + private: /** -- 2.39.5