From 02d5606fba2f98b0f0eabc4fd662ecd1664b1c33 Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Wed, 17 May 2023 22:38:07 -0600 Subject: [PATCH] Minor updates to the NOX solver documentation. --- include/deal.II/trilinos/nox.h | 28 +++++++++++++++++++----- include/deal.II/trilinos/nox.templates.h | 9 ++++---- 2 files changed, 26 insertions(+), 11 deletions(-) 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) -- 2.39.5