From 483b55a05650ad81593a15f2d53fd7df257a30e0 Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Fri, 15 Jul 2016 14:06:59 -0500 Subject: [PATCH] Update documentation of SparseMatrix::mmult. The intent is to make it clearer what happens when rebuilding the sparsity pattern. --- include/deal.II/lac/sparse_matrix.h | 46 ++++++++++++++++++----------- 1 file changed, 29 insertions(+), 17 deletions(-) diff --git a/include/deal.II/lac/sparse_matrix.h b/include/deal.II/lac/sparse_matrix.h index 21a4a52d5a..01d2679993 100644 --- a/include/deal.II/lac/sparse_matrix.h +++ b/include/deal.II/lac/sparse_matrix.h @@ -1154,23 +1154,35 @@ public: * optional vector argument is given, C = A * diag(V) * B, where * diag(V) defines a diagonal matrix with the vector entries. * - * This function assumes that the calling matrix A and B - * have compatible sizes. The size of C will be set within this - * function. - * - * The content as well as the sparsity pattern of the matrix C will be - * changed by this function, so make sure that the sparsity pattern is not - * used somewhere else in your program. This is an expensive operation, so - * think twice before you use this function. - * - * There is an optional flag rebuild_sparsity_pattern that can be - * used to bypass the creation of a new sparsity pattern and instead uses - * the sparsity pattern stored in C. In that case, make sure that - * it really fits. The default is to rebuild the sparsity pattern. - * - * @note Rebuilding the sparsity pattern requires changing it. This means - * that all other matrices that are associated with this sparsity pattern - * will then have invalid entries. + * This function assumes that the calling matrix @p A and the argument @p B + * have compatible sizes. By default, the output matrix @p C will be + * resized appropriately. + * + * By default, i.e., if the optional argument @p rebuild_sparsity_pattern + * is @p true, the sparsity pattern of the matrix C will be + * changed to ensure that all entries that result from the product $AB$ + * can be stored in $C$. This is an expensive operation, and if there is + * a way to predict the sparsity pattern up front, you should probably + * build it yourself before calling this function with @p false as last + * argument. In this case, the rebuilding of the sparsity pattern is + * bypassed. + * + * When setting @p rebuild_sparsity_pattern to @p true (i.e., leaving it + * at the default value), it is important to realize that the matrix + * @p C passed as first argument still has to be initialized with a + * sparsity pattern (either at the time of creation of the SparseMatrix + * object, or via the SparseMatrix::reinit() function). This is because + * we could create a sparsity pattern inside the current function, and + * then associate @p C with it, but there would be no way to transfer + * ownership of this sparsity pattern to anyone once the current function + * finishes. Consequently, the function requires that @p C be already + * associated with a sparsity pattern object, and this object is then + * reset to fit the product of @p A and @p B. + * + * As a consequence of this, however, it is also important to realize + * that the sparsity pattern of @p C is modified and that this would + * render invalid all other SparseMatrix objects that happen + * to also use that sparsity pattern object. */ template void mmult (SparseMatrix &C, -- 2.39.5