From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Fri, 7 Apr 2023 18:11:41 +0000 (-0600)
Subject: Clarifications in commentary in various places.
X-Git-Tag: v9.5.0-rc1~359^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F15047%2Fhead;p=dealii.git

Clarifications in commentary in various places.
---

diff --git a/include/deal.II/lac/affine_constraints.templates.h b/include/deal.II/lac/affine_constraints.templates.h
index f1d018c490..8ddc7c6bf7 100644
--- a/include/deal.II/lac/affine_constraints.templates.h
+++ b/include/deal.II/lac/affine_constraints.templates.h
@@ -3984,8 +3984,12 @@ AffineConstraints<number>::distribute_local_to_global(
                                                           val_ptr);
           const size_type n_values = col_ptr - cols.data();
           if (n_values > 0)
-            global_matrix.add(
-              row, n_values, cols.data(), vals.data(), false, true);
+            global_matrix.add(row,
+                              n_values,
+                              cols.data(),
+                              vals.data(),
+                              /* elide zero additions */ false,
+                              /* sorted by column index */ true);
         }
       else
         internal::AffineConstraints::resolve_matrix_row(
diff --git a/include/deal.II/lac/sparse_matrix.h b/include/deal.II/lac/sparse_matrix.h
index 3277bf8536..72b30d2e8c 100644
--- a/include/deal.II/lac/sparse_matrix.h
+++ b/include/deal.II/lac/sparse_matrix.h
@@ -906,8 +906,8 @@ public:
       const bool                    elide_zero_values = true);
 
   /**
-   * Set several elements in the specified row of the matrix with column
-   * indices as given by <tt>col_indices</tt> to the respective value.
+   * Add the provided values to several elements in the specified row of the
+   * matrix with column indices as given by <tt>col_indices</tt>.
    *
    * The optional parameter <tt>elide_zero_values</tt> can be used to specify
    * whether zero values should be added anyway or these should be filtered
diff --git a/include/deal.II/lac/sparse_matrix.templates.h b/include/deal.II/lac/sparse_matrix.templates.h
index dc9fb42d50..da52a6515b 100644
--- a/include/deal.II/lac/sparse_matrix.templates.h
+++ b/include/deal.II/lac/sparse_matrix.templates.h
@@ -574,7 +574,12 @@ SparseMatrix<number>::add(const size_type  row,
               ++post_diag;
             }
 
-          // add indices before diagonal
+          // Add indices before diagonal. Because the input array
+          // is sorted, and because the entries in this matrix row
+          // are sorted, we can just linearly walk the colnums array
+          // and the input array in parallel, stopping whenever the
+          // former matches the column index of the next index in
+          // the input array:
           size_type counter = 1;
           for (size_type i = 0; i < diag; ++i)
             {
@@ -589,7 +594,7 @@ SparseMatrix<number>::add(const size_type  row,
               val_ptr[counter] += values[i];
             }
 
-          // add indices after diagonal
+          // Then do the same to add indices after the diagonal:
           for (size_type i = post_diag; i < n_cols; ++i)
             {
               while (this_cols[counter] < col_indices[i] &&
@@ -609,6 +614,9 @@ SparseMatrix<number>::add(const size_type  row,
         }
       else
         {
+          // Use the same algorithm as above, but because the matrix is
+          // not square, we can now do without the split for diagonal/
+          // entries before the diagional/entries are the diagonal.
           size_type counter = 0;
           for (size_type i = 0; i < n_cols; ++i)
             {