From 63a4b6ba363e00453915563c41a144192862db80 Mon Sep 17 00:00:00 2001
From: Ryan Grove <rgrove@clemson.edu>
Date: Fri, 20 May 2016 08:28:35 -0400
Subject: [PATCH] Some more changes (incomplete)

---
 examples/step-55/doc/results.dox |  4 ++--
 examples/step-55/step-55.cc      | 25 +++++++++++++++++++------
 2 files changed, 21 insertions(+), 8 deletions(-)

diff --git a/examples/step-55/doc/results.dox b/examples/step-55/doc/results.dox
index 171dac0eae..284f849ee1 100644
--- a/examples/step-55/doc/results.dox
+++ b/examples/step-55/doc/results.dox
@@ -162,5 +162,5 @@ nearly perfect scaling in solve time.
 
 <h3> Possible extensions </h3>
 
-<h4> Extension 1 </h4>
-
+<h4> Use expensive or cheap preconditioner </h4>
+Currently, use_expensive is set to true, but if you set it to false, then you will not be using CG in your calculation of $\widetilde{A^{-1}}$ which is an approximation of $A^{-1}$.  Depending on if you chose to use ILU or GMG, you would just be using ILU or a few v-cycles of GMG, respectively, instead of using them as a preconditioner to CG.
diff --git a/examples/step-55/step-55.cc b/examples/step-55/step-55.cc
index f66d09562c..54a4df6584 100644
--- a/examples/step-55/step-55.cc
+++ b/examples/step-55/step-55.cc
@@ -316,10 +316,13 @@ namespace Step55
 
   // @sect3{ASPECT BlockSchurPreconditioner}
 
-  // This class, which is taken from ASPECT and then slightly modified,
-  // implements the block Schur preconditioner for the Stokes system discussed
-  // above. It is templated on the types
-  // for the preconditioner blocks for velocity and schur complement.
+  // In the following, we will implement a preconditioner that expands a
+  // little bit on the ideas discussed in the Results section of step-22.
+  // Specifically, we will do X, Y, and Z. A further iteration of this
+  // approach is also used in the ASPECT code
+  // (see http://aspect.dealii.org) that solves the Stokes equations in
+  // the context of simulating convection in the earth mantle, and which
+  // has been used to solve problems on many thousands of processors.
   //
   // The bool flag @p do_solve_A in the constructor allows us to either
   // apply the preconditioner for the velocity block once or use an inner
@@ -540,10 +543,13 @@ namespace Step55
         const unsigned int n_levels = triangulation.n_levels();
 
         mg_interface_matrices.resize(0, n_levels-1);
-        mg_interface_matrices.clear ();
+        mg_interface_matrices.clear (); // In contrast to all other container classes' clear() functions which
+                                        // delete the contents of the container, this clear() function
+                                        // calls the clear function of all elements stored by this container.
         mg_matrices.resize(0, n_levels-1);
         mg_matrices.clear ();
         mg_sparsity_patterns.resize(0, n_levels-1);
+        //mg_sparsity_patterns.clear ();
 
         for (unsigned int level=0; level<n_levels; ++level)
           {
@@ -574,6 +580,11 @@ namespace Step55
     const unsigned int n_u = dofs_per_block[0],
                        n_p = dofs_per_block[1];
 
+    // As discussed in the introduction, we need to fix one degree of freedom
+    // of the pressure variable to ensure solvability of the problem. We do this
+    // here by marking n_u as a constrained degree of freedom. But not making it
+    // dependent on any other degree of freedom, this implicitly means that the
+    // value of this degree of freedom will be forced to zero.
     if (solver_type == SolverType::UMFPACK)
       {
         TimerOutput::Scope umfpack_specific(computing_timer, "(UMFPACK specific)");
@@ -873,7 +884,9 @@ namespace Step55
     unsigned int n_iterations_S;
 
     // This is used to pass whether or not we want to solve for A inside
-    // the preconditioner
+    // the preconditioner.  One could change this to false to see if
+    // there is still convergence and if so does the program then run
+    // faster or slower
     const bool use_expensive = true;
 
     SolverFGMRES<BlockVector<double> > solver (solver_control);
-- 
2.39.5