From 39c5a138d0548268eafde94b5e28514d763ac6cb Mon Sep 17 00:00:00 2001
From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Fri, 7 Jan 2022 03:06:52 -0700
Subject: [PATCH] Document a part of step-43 that confused @tjhei.

---
 examples/step-43/doc/intro.dox | 39 +++++++++++++++++++++++++++-------
 1 file changed, 31 insertions(+), 8 deletions(-)

diff --git a/examples/step-43/doc/intro.dox b/examples/step-43/doc/intro.dox
index 658f1971f4..483bfb61e3 100644
--- a/examples/step-43/doc/intro.dox
+++ b/examples/step-43/doc/intro.dox
@@ -59,7 +59,7 @@ Much inspiration for this program comes from step-31 but several of the
 techniques discussed here are original.
 
 
-<h3>Advection-dominated two-phase flow mathematical model.</h3>
+<h3>Advection-dominated two-phase flow mathematical model</h3>
 
 We consider the flow of a two-phase immiscible, incompressible
 fluid. Capillary and gravity effects are neglected, and viscous
@@ -103,7 +103,7 @@ and we arrive at a complete model by also imposing boundary values for the
 saturation variable on the inflow boundary $\mathbf{\Gamma}_{in}$.
 
 
-<h3>Adaptive operator splitting and time stepping.</h3>
+<h3>Adaptive operator splitting and time stepping</h3>
 
 As seen in step-21, solving the flow equations for velocity and pressure are
 the parts of the program that take far longer than the (explicit) updating
@@ -154,7 +154,9 @@ diameter of cell $K$).
 The result is a scheme where neither micro nor macro time
 steps are of uniform length, and both are chosen adaptively.
 
-<h3>Time discretization.</h3>
+
+<h3>Time discretization</h3>
+
 Using this time discretization, we obtain the following set of equations for
 each time step from the IMPES approach (see step-21):
 @f{align*}
@@ -170,7 +172,8 @@ saturation equation becomes
   &\epsilon \left( \frac{S^{(n)}-S^{(n-1)}}{\Delta t^{(n)}_c} \right) + \mathbf{u}^{(n)}_t \cdot \nabla F\left(S^{(n-1)}\right) + F\left(S^{(n-1)}\right)q=0.
 @f}
 
-<h3>Weak form, space discretization for the pressure-velocity part.</h3>
+
+<h3>Weak form, space discretization for the pressure-velocity part</h3>
 
 By multiplying the equations defining the total velocity $\mathbf u_t^{(n)}$ and
 the equation that expresses its divergence in terms of source terms, with test
@@ -201,7 +204,9 @@ the pressure, i.e. $u_h \in Q^d_{p+1}$ and $p_h \in Q_p$, where $p=1$, $d$ is
 the space dimension, and $Q_s$ denotes the space of tensor product Lagrange
 polynomials of degree $s$ in each variable.
 
-<h3>Stabilization, weak form and space discretization for the saturation transport equation.</h3>
+
+<h3>Stabilization, weak form and space discretization for the saturation transport equation</h3>
+
 The chosen $Q_1$ elements for the saturation equation do not lead to a stable
 discretization without upwinding or other kinds of stabilization, and spurious
 oscillations will appear in the numerical solution. Adding an artificial
@@ -294,7 +299,7 @@ $S^{(n-1)}_{(-)}$ and $\mathbf{u}^{(n)}_{t(-)}$ are those taken from the
 neighboring boundary $\partial\Omega_{(-)}$.
 
 
-<h3>Adaptive mesh refinement.</h3>
+<h3>Adaptive mesh refinement</h3>
 
 Choosing meshes adaptively to resolve sharp
 saturation fronts is an essential ingredient to achieve efficiency in our
@@ -314,7 +319,7 @@ out to not be a very useful criterion since it leads to refinement basically
 everywhere. We only show it here for illustrative purposes.
 
 
-<h3>Linear system and its preconditioning.</h3>
+<h3>The linear system and its preconditioning</h3>
 
 Following the discretization of the governing equations
 discussed above, we
@@ -475,7 +480,8 @@ where the mass matrix $\mathbf{M}^{S}$ is solved by the conjugate gradient
 method, using an incomplete Cholesky decomposition as preconditioner once
 more.
 
-<h3>The test cases.</h3>
+
+<h3>The test cases</h3>
 
 @note
 The implementation discussed here uses and extends
@@ -540,6 +546,23 @@ cases are listed in the following table:
 </table>
 
 
+
+<h3>A note on the implementation</h3>
+
+We have mentioned many areas above in which this program improves over the step-20
+and step-21 programs upon which it is based. It also uses the Trilinos interfaces
+for its vectors and matrices; this specifically has the advantage that we can use
+an excellent implementation of the Incomplete Cholesky method we use as preconditioners
+for both the top left and bottom right blocks of the $2\times 2$ matrix that describes
+the flow portion of the coupled problem.
+
+We note that while we use the TrilinosWrappers::MPI::BlockVector class to store
+vectors, the program does not actually use MPI (or any other way to run in
+parallel): There is no non-MPI vector class in the TrilinosWrappers namespace,
+but we can use the MPI version to also run a sequential code as we do here.
+
+
+
 <h3>List of references</h3>
 
 
-- 
2.39.5