Merge pull request geodynamics#5686 from bangerth/hack-spd-2

Better document the SPD safety factor.

Author: gassmoeller

source/simulator/newton.cc

@@ -220,11 +220,13 @@ namespace aspect
                              "When stabilizing the Newton matrix, we can encounter situations where the coefficient inside the elliptic (top-left) "
                              "block becomes negative or zero. This coefficient has the form $1+x$ where $x$ can sometimes be smaller than $-1$. In "
                              "this case, the top-left block of the matrix is no longer positive definite, and both preconditioners and iterative "
-                             "solvers may fail. To prevent this, the stabilization computes an $\\alpha$ so that $1+\\alpha x$ is never negative. "
-                             "This $\\alpha$ is chosen as $1$ if $x\\ge -1$, and $\\alpha=-\\frac 1x$ otherwise. (Note that this always leads to "
-                             "$0\\le \\alpha \\le 1$.)  On the other hand, we also want to stay away from $1+\\alpha x=0$, and so modify the choice of "
-                             "$\\alpha$ to be $1$ if $x\\ge -c$, and $\\alpha=-\\frac cx$ with a $c$ between zero and one. This way, if $c<1$, we are "
-                             "assured that $1-\\alpha x>c$, i.e., bounded away from zero.");
+                             "solvers may fail. To prevent this, the stabilization computes an $\\alpha$ so that $1+\\alpha x$ is never negative "
+                             "and so that always "
+                             "$0\\le \\alpha \\le 1$.  On the other hand, we also want to stay away from $1+\\alpha x=0$, and so modify the choice of "
+                             "$\\alpha$ by a factor $c$ between zero and one so that if $c<1$, we are "
+                             "assured that $1+\\alpha x>0$, i.e., bounded away from zero. If $c=1$, we allow $1+\\alpha x=0$, i.e., an "
+                             "unsafe situation. If $c=0$, then $\\alpha$ is always set to zero which guarantees the desired property that "
+                             "$1+\\alpha x=1>0$, but at the cost of a diminished convergence rate of the Newton method.");
 
           prm.declare_entry ("Use Eisenstat Walker method for Picard iterations", "false",
                              Patterns::Bool(),