From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Thu, 18 May 2023 04:38:07 +0000 (-0600)
Subject: Minor updates to the NOX solver documentation.
X-Git-Tag: v9.5.0-rc1~220^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=02d5606fba2f98b0f0eabc4fd662ecd1664b1c33;p=dealii.git

Minor updates to the NOX solver documentation.
---

diff --git a/include/deal.II/trilinos/nox.h b/include/deal.II/trilinos/nox.h
index 3ca2cc2612..32bb5065ff 100644
--- a/include/deal.II/trilinos/nox.h
+++ b/include/deal.II/trilinos/nox.h
@@ -134,10 +134,18 @@ namespace TrilinosWrappers
       unsigned int threshold_nonlinear_iterations;
 
       /**
-       * Max number of linear iterations after which the preconditioner
-       * should be updated. This is only used if
-       * solve_with_jacobian_and_track_n_linear_iterations has been given
-       * a target (i.e., it is not empty).
+       * A number that indicates how many iterations a linear solver
+       * should at most perform before the preconditioner should
+       * be updated. The use of this variable is predicated on the
+       * idea that one can keep using a preconditioner built earlier
+       * as long as it is a good preconditioner for the matrix currently
+       * in use -- where "good" is defined as leading to a number of
+       * iterations to solve linear systems less than the threshold
+       * given by the current variable.
+       *
+       * This variable is only used if the
+       * NOXSolver::solve_with_jacobian_and_track_n_linear_iterations
+       * function object has been given a target (i.e., it is not empty).
        */
       unsigned int threshold_n_linear_iterations;
 
@@ -280,8 +288,16 @@ namespace TrilinosWrappers
      * (i.e., more precisely: the linearization point $u$ above) is
      * the one computed when the `setup_jacobian` function was last called.
      *
-     * @note This function is optional and is used in the case of certain
-     * configurations.
+     * @note This function is used if `solve_with_jacobian` is not
+     *   provided. Its return value is compared again
+     *   AdditionalFlags::threshold_n_linear_iterations; if it is
+     *   larger, the preconditioner will be built before the next
+     *   linear system is solved. The use of this approach is predicated on the
+     * idea that one can keep using a preconditioner built earlier
+     * as long as it is a good preconditioner for the matrix currently
+     * in use -- where "good" is defined as leading to a number of
+     * iterations to solve linear systems less than the threshold
+     * given by the current variable.
      *
      * @note This variable represents a
      * @ref GlossUserProvidedCallBack "user provided callback".
diff --git a/include/deal.II/trilinos/nox.templates.h b/include/deal.II/trilinos/nox.templates.h
index 57d8974504..044c3aa088 100644
--- a/include/deal.II/trilinos/nox.templates.h
+++ b/include/deal.II/trilinos/nox.templates.h
@@ -1009,9 +1009,8 @@ namespace TrilinosWrappers
                (n_last_linear_iterations >
                 additional_data.threshold_n_linear_iterations));
 
-            if ((update_preconditioner == false) &&
-                (update_preconditioner_predicate != nullptr))
-              update_preconditioner = update_preconditioner_predicate();
+            if (update_preconditioner_predicate)
+              update_preconditioner |= update_preconditioner_predicate();
 
             if (update_preconditioner)
               flag = internal::NOXWrappers::call_and_possibly_capture_exception(
@@ -1028,7 +1027,7 @@ namespace TrilinosWrappers
           ExcMessage(
             "No apply_jacobian function has been attached to the NOXSolver object."));
 
-        n_jacobian_applications++;
+        ++n_jacobian_applications;
 
         // apply Jacobian
         return internal::NOXWrappers::call_and_possibly_capture_exception(
@@ -1037,7 +1036,7 @@ namespace TrilinosWrappers
 
       /* solve_with_jacobian function */
       [&](const VectorType &f, VectorType &x, const double tolerance) -> int {
-        n_nonlinear_iterations++;
+        ++n_nonlinear_iterations;
 
         // invert Jacobian
         if (solve_with_jacobian)