From da5fe1494b220e03ab799d44bb2fa34b9267d128 Mon Sep 17 00:00:00 2001
From: Wolfgang Bangerth <bangerth@math.tamu.edu>
Date: Mon, 9 Mar 2015 14:16:03 -0500
Subject: [PATCH] Document changes to
 TrilinosWrappers::SparseMatrix::clear_row().

While there, also remove the second, nonsensical call to compress().
---
 doc/news/changes.h                           |  8 +++++
 include/deal.II/lac/trilinos_sparse_matrix.h | 31 +++++++++++++++++---
 source/lac/trilinos_sparse_matrix.cc         |  7 -----
 3 files changed, 35 insertions(+), 11 deletions(-)

diff --git a/doc/news/changes.h b/doc/news/changes.h
index 67cbd6fd83..47cad75662 100644
--- a/doc/news/changes.h
+++ b/doc/news/changes.h
@@ -38,6 +38,14 @@ inconvenience this causes.
 </p>
 
 <ol>
+  <li> Changed: The TrilinosWrappers::SparseMatrix::clear_row() function used
+  to call TrilinosWrappers::SparseMatrix::compress() before doing its work,
+  but this is neither efficient nor safe. You will now have to do this
+  yourself after assembling a matrix and before clearing rows.
+  <br>
+  (Wolfgang Bangerth, 2015/03/09)
+  </li>
+
   <li> Changed: Implicit conversion from Tensor@<1,dim@> to Point@<dim@> was
   previously possible. This has now been prohibited (but you can still
   do the conversion with an explicit cast) as such conversions are
diff --git a/include/deal.II/lac/trilinos_sparse_matrix.h b/include/deal.II/lac/trilinos_sparse_matrix.h
index 10cabcf12e..b0ec65344f 100644
--- a/include/deal.II/lac/trilinos_sparse_matrix.h
+++ b/include/deal.II/lac/trilinos_sparse_matrix.h
@@ -1288,10 +1288,7 @@ namespace TrilinosWrappers
     /**
      * Remove all elements from this <tt>row</tt> by setting them to zero. The
      * function does not modify the number of allocated nonzero entries, it
-     * only sets some entries to zero. It may drop them from the sparsity
-     * pattern, though (but retains the allocated memory in case new entries
-     * are again added later). Note that this is a global operation, so this
-     * needs to be done on all MPI processes.
+     * only sets the entries to zero.
      *
      * This operation is used in eliminating constraints (e.g. due to hanging
      * nodes) and makes sure that we can write this modification to the matrix
@@ -1301,6 +1298,19 @@ namespace TrilinosWrappers
      *
      * The second parameter can be used to set the diagonal entry of this row
      * to a value different from zero. The default is to set it to zero.
+     *
+     * @note If the matrix is stored in parallel across multiple
+     * processors using MPI, this function only touches rows that are
+     * locally stored and simply ignores all other row
+     * indices. Further, in the context of parallel computations, you
+     * will get into trouble if you clear a row while other processors
+     * still have pending writes or additions into the same row. In
+     * other words, if another processor still wants to add something
+     * to an element of a row and you call this function to zero out
+     * the row, then the next time you call compress() may add the
+     * remote value to the zero you just created. Consequently, you
+     * will want to call compress() after you made the last
+     * modifications to a matrix and before starting to clear rows.
      */
     void clear_row (const size_type      row,
                     const TrilinosScalar new_diag_value = 0);
@@ -1312,6 +1322,19 @@ namespace TrilinosWrappers
      * cleared rows to something different from zero. Note that all of these
      * diagonal entries get the same value -- if you want different values for
      * the diagonal entries, you have to set them by hand.
+     *
+     * @note If the matrix is stored in parallel across multiple
+     * processors using MPI, this function only touches rows that are
+     * locally stored and simply ignores all other row
+     * indices. Further, in the context of parallel computations, you
+     * will get into trouble if you clear a row while other processors
+     * still have pending writes or additions into the same row. In
+     * other words, if another processor still wants to add something
+     * to an element of a row and you call this function to zero out
+     * the row, then the next time you call compress() may add the
+     * remote value to the zero you just created. Consequently, you
+     * will want to call compress() after you made the last
+     * modifications to a matrix and before starting to clear rows.
      */
     void clear_rows (const std::vector<size_type> &rows,
                      const TrilinosScalar          new_diag_value = 0);
diff --git a/source/lac/trilinos_sparse_matrix.cc b/source/lac/trilinos_sparse_matrix.cc
index 4d808c7a3e..c7667ec143 100644
--- a/source/lac/trilinos_sparse_matrix.cc
+++ b/source/lac/trilinos_sparse_matrix.cc
@@ -1104,13 +1104,6 @@ namespace TrilinosWrappers
   {
     for (size_type row=0; row<rows.size(); ++row)
       clear_row(rows[row], new_diag_value);
-
-    // This function needs to be called
-    // on all processors. We change some
-    // data, so we need to flush the
-    // buffers to make sure that the
-    // right data is used.
-    compress(VectorOperation::insert);
   }
 
 
-- 
2.39.5