Document changes to TrilinosWrappers::SparseMatrix::clear_row().

While there, also remove the second, nonsensical call to compress().

diff --git a/doc/news/changes.h b/doc/news/changes.h
index 67cbd6fd839442d9af0fb84dea2379ec4d969d2a..47cad75662b022e177c9334bbdea7dc04a11439a 100644 (file)
--- 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 10cabcf12e114414ef6dc8f4be687ff9bb12cc37..b0ec65344f4b6ad0effacedb1882c26585127889 100644 (file)
--- 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 4d808c7a3e61caf2c704bd38a89772eebc09feb5..c7667ec143a296257a4d16d1951d68d723f85cce 100644 (file)
--- 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);
   }