From: Wolfgang Bangerth Date: Sun, 15 Nov 2015 20:00:01 +0000 (-0600) Subject: Update documentation about sparsity patterns. X-Git-Tag: v8.4.0-rc2~227^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=8707fe3aebc01c5490b2567ce5d99399c78fa3d3;p=dealii.git Update documentation about sparsity patterns. --- diff --git a/doc/doxygen/headers/matrices.h b/doc/doxygen/headers/matrices.h index 33be7ff857..299e0218c2 100644 --- a/doc/doxygen/headers/matrices.h +++ b/doc/doxygen/headers/matrices.h @@ -1,6 +1,6 @@ // --------------------------------------------------------------------- // -// Copyright (C) 2003 - 2013 by the deal.II authors +// Copyright (C) 2003 - 2013, 2015 by the deal.II authors // // This file is part of the deal.II library. // @@ -128,6 +128,22 @@ class MATRIX /** * @defgroup Sparsity Sparsity patterns * + * Almost all finite element formulations lead to matrices that are + * "sparse", i.e., for which the number of nonzero elements per row is + * (i) relatively small compared to the overall size of the matrix, + * and (ii) bounded by a fixed number that does not grow if the mesh + * is refined. For such cases, it is more efficient to not store + * all elements of the matrix, but only those that are actually + * (or may be) nonzero. This requires storing, for each row, the + * column indices of the nonzero entries (we call this the "sparsity + * pattern") as well as the actual values of these nonzero + * entries. (In practice, it sometimes happens that some of the + * nonzero values are, in fact, zero. Sparsity patterns and sparse + * matrices only intend to provision space for entries that may + * be nonzero, and do so at a time when we don't know yet what values + * these entries will ultimately have; they may have a zero value if a + * coefficient or cell happens to have particular values.) + * * In deal.II, sparsity patterns are typically separated from the actual * sparse matrices (with the exception of the SparseMatrixEZ class and some * classes from interfaces to external libraries such as PETSc). The reason is diff --git a/include/deal.II/lac/sparse_matrix.h b/include/deal.II/lac/sparse_matrix.h index 27d868e3c6..85b1451ec8 100644 --- a/include/deal.II/lac/sparse_matrix.h +++ b/include/deal.II/lac/sparse_matrix.h @@ -431,18 +431,16 @@ namespace SparseMatrixIterators //TODO: Add multithreading to the other vmult functions. /** - * Sparse matrix. This class implements the function to store values in the - * locations of a sparse matrix denoted by a SparsityPattern. The separation - * of sparsity pattern and values is done since one can store data elements of - * different type in these locations without the SparsityPattern having to - * know this, and more importantly one can associate more than one matrix with - * the same sparsity pattern. + * Sparse matrix. This class implements the functionality to store + * matrix entry values in the locations denoted by a + * SparsityPattern. See @ref Sparsity for a discussion about the + * separation between sparsity patterns and matrices. * * The elements of a SparseMatrix are stored in the same order in which the * SparsityPattern class stores its entries. Within each row, elements are * generally stored left-to-right in increasing column index order; the - * exception to this rule is that if the matrix is square (n_rows() == - * n_columns()), then the diagonal entry is stored as the first element in + * exception to this rule is that if the matrix is square (m() == + * n()), then the diagonal entry is stored as the first element in * each row to make operations like applying a Jacobi or SSOR preconditioner * faster. As a consequence, if you traverse the elements of a row of a * SparseMatrix with the help of iterators into this object (using diff --git a/include/deal.II/lac/sparsity_pattern.h b/include/deal.II/lac/sparsity_pattern.h index e27f6c1f1e..ea9a3190e3 100644 --- a/include/deal.II/lac/sparsity_pattern.h +++ b/include/deal.II/lac/sparsity_pattern.h @@ -295,10 +295,13 @@ namespace SparsityPatternIterators /** - * Structure representing the sparsity pattern of a sparse matrix. This class - * is an example of the "static" type of - * @ref Sparsity. - * It uses the compressed row storage (CSR) format to store data. + * A class that can store which elements of a matrix are nonzero (or, + * in fact, may be nonzero) and for which we have to allocate + * memory to store their values. This class is an example of the + * "static" type of sparsity patters (see @ref Sparsity). It uses the + * compressed + * row storage (CSR) format to store data, and is used as the + * basis for the SparseMatrix class. * * The elements of a SparsityPattern, corresponding to the places where * SparseMatrix objects can store nonzero entries, are stored row-by-row. @@ -318,8 +321,7 @@ namespace SparsityPatternIterators * systems, it is rarely set up directly due to the way it stores its * information. Rather, one typically goes through an intermediate format * first, see for example the step-2 tutorial program as well as the - * documentation module - * @ref Sparsity. + * documentation module @ref Sparsity. * * @author Wolfgang Bangerth, Guido Kanschat and others */