From: Guido Kanschat Date: Fri, 29 May 2015 15:52:51 +0000 (+0200) Subject: Add some documentation on the special structure of RelaxationBlock::AdditionalData X-Git-Tag: v8.3.0-rc1~140^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F975%2Fhead;p=dealii.git Add some documentation on the special structure of RelaxationBlock::AdditionalData --- diff --git a/include/deal.II/lac/relaxation_block.h b/include/deal.II/lac/relaxation_block.h index dea9131db4..a9e6a32263 100644 --- a/include/deal.II/lac/relaxation_block.h +++ b/include/deal.II/lac/relaxation_block.h @@ -69,7 +69,10 @@ public: typedef types::global_dof_index size_type; /** - * Parameters for block relaxation methods. + * Parameters for block relaxation methods. In addition to typical + * control parameters like #relaxation, this object also contains + * the block structure in #block_list and an optional ordering of + * the blocks in #order. */ class AdditionalData : public Subscriptor { @@ -82,7 +85,9 @@ public: const bool same_diagonal = false); /** - * The mapping from indices to blocks. + * The mapping from indices to blocks. Each row of this pattern + * enumerates the indices constituting a diagonal block to be + * inverted. */ SparsityPattern block_list; @@ -92,12 +97,21 @@ public: double relaxation; /** - * Invert diagonal during initialization. + * Invert diagonal during initialization. Alternatively, diagonal + * blocks are inverted on the fly, whenever they are used. While + * inverting blocks in advance requires more memory, it usually + * saves a lot of computation. See #same_diagonal on how you can + * avoid memory overhead. */ bool invert_diagonal; /** - * Assume all diagonal blocks are equal to save memory. + * Assume all diagonal blocks are equal to save memory. If this + * flag is true, then only the first diagonal block of the matrix + * is inverted and stored. It is then used for all other blocks. + * + * \note Avoid setting this true if your blocks are not equal, in + * particularr if their sizes differ. */ bool same_diagonal; /** @@ -106,9 +120,11 @@ public: typename PreconditionBlockBase::Inversion inversion; /** - * The if #inversion is SVD, the threshold below which a singular value - * will be considered zero and thus not inverted. This parameter is used - * in the call to LAPACKFullMatrix::compute_inverse_svd(). + * If #inversion is SVD, we can compute the Penrose-Moore inverse + * of the blocks. In order to do so, we can specify here the + * threshold below which a singular value will be considered zero + * and thus not inverted. This parameter is used in the call to + * LAPACKFullMatrix::compute_inverse_svd(). */ double threshold; @@ -140,11 +156,14 @@ public: }; /** - * Initialize matrix and block size. We store the matrix and the block size - * in the preconditioner object. In a second step, the inverses of the - * diagonal blocks may be computed. + * Initialize matrix and additional information. In a second step, + * the inverses of the diagonal blocks may be computed. * - * Additionally, a relaxation parameter for derived classes may be provided. + * Note that AdditionalData, different from other preconditioners, + * defines quite large objects, and that therefore the object is not + * copied, but rather a pointer is stored. Thus, the lifetime of + * additional_data hast to exceed the lifetime of this + * object. */ void initialize (const MATRIX &A, const AdditionalData ¶meters);