Update documentation about sparsity patterns.

diff --git a/doc/doxygen/headers/matrices.h b/doc/doxygen/headers/matrices.h
index 33be7ff8574be837a8e25a0e13c090d0994782ac..299e0218c259c8f2e0ced1eb74d2047dadfd77fb 100644 (file)
--- 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
+ * <i>all</i> 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 <i>may</i>
+ * 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 27d868e3c66d4d778152a806f69bb6876538a049..85b1451ec83321a41cb81bd23006937799030b85 100644 (file)
--- 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 e27f6c1f1e2d2a9ec09f71b882d9cab8951d45dd..ea9a3190e3743d09d3f9dabc14de6025c0d766b8 100644 (file)
--- 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, <i>may</i> 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
+ * <a href="https://en.wikipedia.org/wiki/Sparse_matrix">compressed
+ * row storage (CSR)</a> 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
  */