From: bangerth Date: Mon, 11 Feb 2013 20:14:12 +0000 (+0000) Subject: Rename a variable. Add documentation. X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=6927e07682c30c34b649eaf849b920632de2ea2c;p=dealii-svn.git 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 af8c02dc53..83e29e38b2 100644 --- 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 * Constness=false, 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 all + * 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 class Iterator @@ -1995,10 +2008,10 @@ namespace SparseMatrixIterators inline Accessor:: 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::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::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::Reference & Accessor::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::Reference & Accessor::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::Reference & Accessor::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::Reference & Accessor::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::Reference & Accessor::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 faa6e0ef46..5bd0e75728 100644 --- 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 all + * 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; } }