Rename a variable. Add documentation.

git-svn-id: https://svn.dealii.org/trunk@28315 0785d39b-7218-0410-832d-ea1e28bc413d

diff --git a/deal.II/include/deal.II/lac/sparse_matrix.h b/deal.II/include/deal.II/lac/sparse_matrix.h
index af8c02dc53848bccbcbc4dd661fa0c63ff3cd78e..83e29e38b20f1c4f51e8af99596bfe8f799cf494 100644 (file)
--- a/deal.II/include/deal.II/lac/sparse_matrix.h
+++ b/deal.II/include/deal.II/lac/sparse_matrix.h
@@ -102,7 +102,7 @@ namespace SparseMatrixIterators
      * Constructor.
      */
     Accessor (MatrixType         *matrix,
-              const std::size_t   index_with_matrix);
+              const std::size_t   index_within_matrix);
 
     /**
      * Constructor. Construct the end accessor for the given matrix.
@@ -303,6 +303,19 @@ namespace SparseMatrixIterators
    * Since there is a specialization of this class for
    * <tt>Constness=false</tt>, this class is for iterators to constant
    * matrices.
+   *
+   * @note This class operates directly on the internal data structures of the
+   * SparsityPattern and SparseMatrix classes. As a consequence, some operations
+   * are cheap and some are not. In particular, it is cheap to access the column
+   * index and the value of an entry pointed to. On the other hand, it is expensive
+   * to access the row index (this requires $O(\log(N))$ operations for a
+   * matrix with $N$ row). As a consequence, when you design algorithms that
+   * use these iterators, it is common practice to not loop over <i>all</i>
+   * elements of a sparse matrix at once, but to have an outer loop over
+   * all rows and within this loop iterate over the elements of this row.
+   * This way, you only ever need to dereference the iterator to obtain
+   * the column indices and values whereas the (expensive) lookup of the row index
+   * can be avoided by using the loop index instead.
    */
   template <typename number, bool Constness>
   class Iterator
@@ -1995,10 +2008,10 @@ namespace SparseMatrixIterators
   inline
   Accessor<number,true>::
   Accessor (const MatrixType   *matrix,
-            const std::size_t   index)
+            const std::size_t   index_within_matrix)
     :
     SparsityPatternIterators::Accessor (&matrix->get_sparsity_pattern(),
-                                        index),
+                                        index_within_matrix),
     matrix (matrix)
   {}
 
@@ -2031,8 +2044,8 @@ namespace SparseMatrixIterators
   number
   Accessor<number, true>::value () const
   {
-    AssertIndexRange(a_index, matrix->n_nonzero_elements());
-    return matrix->val[a_index];
+    AssertIndexRange(index_within_sparsity, matrix->n_nonzero_elements());
+    return matrix->val[index_within_sparsity];
   }
 
 
@@ -2061,8 +2074,8 @@ namespace SparseMatrixIterators
   inline
   Accessor<number, false>::Reference::operator number() const
   {
-    AssertIndexRange(accessor->a_index, accessor->matrix->n_nonzero_elements());
-    return accessor->matrix->val[accessor->a_index];
+    AssertIndexRange(accessor->index_within_sparsity, accessor->matrix->n_nonzero_elements());
+    return accessor->matrix->val[accessor->index_within_sparsity];
   }
 
 
@@ -2072,8 +2085,8 @@ namespace SparseMatrixIterators
   const typename Accessor<number, false>::Reference &
   Accessor<number, false>::Reference::operator = (const number n) const
   {
-    AssertIndexRange(accessor->a_index, accessor->matrix->n_nonzero_elements());
-    accessor->matrix->val[accessor->a_index] = n;
+    AssertIndexRange(accessor->index_within_sparsity, accessor->matrix->n_nonzero_elements());
+    accessor->matrix->val[accessor->index_within_sparsity] = n;
     return *this;
   }
 
@@ -2084,8 +2097,8 @@ namespace SparseMatrixIterators
   const typename Accessor<number, false>::Reference &
   Accessor<number, false>::Reference::operator += (const number n) const
   {
-    AssertIndexRange(accessor->a_index, accessor->matrix->n_nonzero_elements());
-    accessor->matrix->val[accessor->a_index] += n;
+    AssertIndexRange(accessor->index_within_sparsity, accessor->matrix->n_nonzero_elements());
+    accessor->matrix->val[accessor->index_within_sparsity] += n;
     return *this;
   }
 
@@ -2096,8 +2109,8 @@ namespace SparseMatrixIterators
   const typename Accessor<number, false>::Reference &
   Accessor<number, false>::Reference::operator -= (const number n) const
   {
-    AssertIndexRange(accessor->a_index, accessor->matrix->n_nonzero_elements());
-    accessor->matrix->val[accessor->a_index] -= n;
+    AssertIndexRange(accessor->index_within_sparsity, accessor->matrix->n_nonzero_elements());
+    accessor->matrix->val[accessor->index_within_sparsity] -= n;
     return *this;
   }
 
@@ -2108,8 +2121,8 @@ namespace SparseMatrixIterators
   const typename Accessor<number, false>::Reference &
   Accessor<number, false>::Reference::operator *= (const number n) const
   {
-    AssertIndexRange(accessor->a_index, accessor->matrix->n_nonzero_elements());
-    accessor->matrix->val[accessor->a_index] *= n;
+    AssertIndexRange(accessor->index_within_sparsity, accessor->matrix->n_nonzero_elements());
+    accessor->matrix->val[accessor->index_within_sparsity] *= n;
     return *this;
   }
 
@@ -2120,8 +2133,8 @@ namespace SparseMatrixIterators
   const typename Accessor<number, false>::Reference &
   Accessor<number, false>::Reference::operator /= (const number n) const
   {
-    AssertIndexRange(accessor->a_index, accessor->matrix->n_nonzero_elements());
-    accessor->matrix->val[accessor->a_index] /= n;
+    AssertIndexRange(accessor->index_within_sparsity, accessor->matrix->n_nonzero_elements());
+    accessor->matrix->val[accessor->index_within_sparsity] /= n;
     return *this;
   }
 
@@ -2320,7 +2333,7 @@ namespace SparseMatrixIterators
     Assert (&accessor.get_matrix() == &other.accessor.get_matrix(),
             ExcInternalError());
 
-    return (*this)->a_index - other->a_index;
+    return (*this)->index_within_sparsity - other->index_within_sparsity;
   }
 
 

diff --git a/deal.II/include/deal.II/lac/sparsity_pattern.h b/deal.II/include/deal.II/lac/sparsity_pattern.h
index faa6e0ef465ae7f2b02d1f42eb0440425e51161b..5bd0e75728d009b027f2b62d74f755c644a8e69a 100644 (file)
--- a/deal.II/include/deal.II/lac/sparsity_pattern.h
+++ b/deal.II/include/deal.II/lac/sparsity_pattern.h
@@ -130,7 +130,7 @@ namespace SparsityPatternIterators
     unsigned int row () const;
 
     /**
-     * Index in row of the element represented by this object. This function
+     * Index within the current row of the element represented by this object. This function
      * can only be called for entries for which is_valid_entry() is true.
      */
     unsigned int index () const;
@@ -173,9 +173,13 @@ namespace SparsityPatternIterators
     const SparsityPattern *sparsity_pattern;
 
     /**
-     * Index in global sparsity pattern.
+     * Index in global sparsity pattern. This index represents the location
+     * the iterator/accessor points to within the array of the SparsityPattern
+     * class that stores the column numbers. It is also the index within the
+     * values array of a sparse matrix that stores the corresponding value of
+     * this site.
      */
-    std::size_t a_index;
+    std::size_t index_within_sparsity;
 
     /**
      * Move the accessor to the next nonzero entry in the matrix.
@@ -205,6 +209,19 @@ namespace SparsityPatternIterators
    * that the elements of a row are actually traversed in an order in which
    * columns monotonically increase. See the documentation of the
    * SparsityPattern class for more information.
+   *
+   * @note This class operates directly on the internal data structures of the
+   * SparsityPattern class. As a consequence, some operations are cheap and
+   * some are not. In particular, it is cheap to access the column index of
+   * the sparsity pattern entry pointed to. On the other hand, it is expensive
+   * to access the row index (this requires $O(\log(N))$ operations for a
+   * matrix with $N$ row). As a consequence, when you design algorithms that
+   * use these iterators, it is common practice to not loop over <i>all</i>
+   * elements of a sparsity pattern at once, but to have an outer loop over
+   * all rows and within this loop iterate over the elements of this row.
+   * This way, you only ever need to dereference the iterator to obtain
+   * the column indices whereas the (expensive) lookup of the row index
+   * can be avoided by using the loop index instead.
    */
   class Iterator
   {
@@ -1414,7 +1431,7 @@ namespace SparsityPatternIterators
             const unsigned int     i)
     :
     sparsity_pattern(sparsity_pattern),
-    a_index(sparsity_pattern->rowstart[r]+i)
+    index_within_sparsity(sparsity_pattern->rowstart[r]+i)
   {}
 
 
@@ -1424,7 +1441,7 @@ namespace SparsityPatternIterators
             const std::size_t      i)
     :
     sparsity_pattern(sparsity_pattern),
-    a_index(i)
+    index_within_sparsity(i)
   {}
 
 
@@ -1433,7 +1450,7 @@ namespace SparsityPatternIterators
   Accessor (const SparsityPattern *sparsity_pattern)
     :
     sparsity_pattern(sparsity_pattern),
-    a_index(sparsity_pattern->rowstart[sparsity_pattern->rows])
+    index_within_sparsity(sparsity_pattern->rowstart[sparsity_pattern->rows])
   {}
 
 
@@ -1441,9 +1458,9 @@ namespace SparsityPatternIterators
   bool
   Accessor::is_valid_entry () const
   {
-    return (a_index < sparsity_pattern->rowstart[sparsity_pattern->rows]
+    return (index_within_sparsity < sparsity_pattern->rowstart[sparsity_pattern->rows]
             &&
-            sparsity_pattern->colnums[a_index]
+            sparsity_pattern->colnums[index_within_sparsity]
             != SparsityPattern::invalid_entry);
   }
 
@@ -1457,7 +1474,7 @@ namespace SparsityPatternIterators
     const std::size_t * insert_point =
       std::upper_bound(sparsity_pattern->rowstart,
                        sparsity_pattern->rowstart + sparsity_pattern->rows + 1,
-                       a_index);
+                       index_within_sparsity);
     return insert_point - sparsity_pattern->rowstart - 1;
   }
 
@@ -1468,7 +1485,7 @@ namespace SparsityPatternIterators
   {
     Assert (is_valid_entry() == true, ExcInvalidIterator());
 
-    return (sparsity_pattern->colnums[a_index]);
+    return (sparsity_pattern->colnums[index_within_sparsity]);
   }
 
 
@@ -1478,7 +1495,7 @@ namespace SparsityPatternIterators
   {
     Assert (is_valid_entry() == true, ExcInvalidIterator());
 
-    return a_index - sparsity_pattern->rowstart[row()];
+    return index_within_sparsity - sparsity_pattern->rowstart[row()];
   }
 
 
@@ -1489,7 +1506,7 @@ namespace SparsityPatternIterators
   Accessor::operator == (const Accessor &other) const
   {
     return (sparsity_pattern == other.sparsity_pattern &&
-            a_index == other.a_index);
+            index_within_sparsity == other.index_within_sparsity);
   }
 
 
@@ -1501,7 +1518,7 @@ namespace SparsityPatternIterators
     Assert (sparsity_pattern == other.sparsity_pattern,
             ExcInternalError());
 
-    return a_index < other.a_index;
+    return index_within_sparsity < other.index_within_sparsity;
   }
 
 
@@ -1509,9 +1526,9 @@ namespace SparsityPatternIterators
   void
   Accessor::advance ()
   {
-    Assert (a_index < sparsity_pattern->rowstart[sparsity_pattern->rows],
+    Assert (index_within_sparsity < sparsity_pattern->rowstart[sparsity_pattern->rows],
             ExcIteratorPastEnd());
-    ++a_index;
+    ++index_within_sparsity;
   }
 
 
@@ -1605,7 +1622,7 @@ namespace SparsityPatternIterators
     Assert (accessor.sparsity_pattern == other.accessor.sparsity_pattern,
             ExcInternalError());
 
-    return (*this)->a_index - other->a_index;
+    return (*this)->index_within_sparsity - other->index_within_sparsity;
   }
 }