From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Mon, 1 Jul 2024 20:08:08 +0000 (-0600)
Subject: Rename a second callback in PETScWrappers::TimeStepper.
X-Git-Tag: v9.6.0-rc1~137^2~2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=97b3a7dee63b200c0df5091716627fbd1b925d49;p=dealii.git

Rename a second callback in PETScWrappers::TimeStepper.
---

diff --git a/include/deal.II/lac/petsc_ts.h b/include/deal.II/lac/petsc_ts.h
index 9266342c6c..ebefa3d4f8 100644
--- a/include/deal.II/lac/petsc_ts.h
+++ b/include/deal.II/lac/petsc_ts.h
@@ -606,26 +606,40 @@ namespace PETScWrappers
     std::function<void(const real_type t, VectorType &y)> distribute;
 
     /**
-     * Callback to set up mesh adaption.
+     * This callback is equivalent to `decide_and_prepare_for_remeshing`
+     * except that it returns the decision whether or not to stop
+     * operations via the last reference argument of the function
+     * object instead of a plain return value. This callback is
+     * deprecated. Use `decide_and_prepare_for_remeshing` instead.
+     */
+    std::function<void(const real_type    t,
+                       const unsigned int step,
+                       const VectorType  &y,
+                       bool              &resize)>
+      decide_for_coarsening_and_refinement;
+
+    /**
+     * A callback that returns whether or not to stop time stepping at the
+     * current moment for mesh adaptation. If the callback returns `true`,
+     * then the time stepper stops time integration for now, saves some state,
+     * calls the `interpolate` callback, and then resumes time integration.
+     * Either in the current callback or the `interpolate` callback, the
+     * user code needs to perform the mesh refinement.
      *
-     * Implementation of this function is optional.
-     * @p resize must be set to true if mesh adaption is to be performed, false
+     * Implementation of this function is optional. The callback
+     * must return `true` if mesh adaption is to be performed, `false`
      * otherwise.
      * The @p y vector contains the current solution, @p t the current time,
      * @ step the step number.
-     * Solution transfer and actual mesh adaption must be performed in a
-     * separate callback, TimeStepper::interpolate
      *
      * @note This variable represents a
      * @ref GlossUserProvidedCallBack "user provided callback".
      * See there for a description of how to deal with errors and other
      * requirements and conventions.
      */
-    std::function<void(const real_type    t,
-                       const unsigned int step,
-                       const VectorType  &y,
-                       bool              &resize)>
-      decide_for_coarsening_and_refinement;
+    std::function<
+      bool(const real_type t, const unsigned int step, const VectorType &y)>
+      decide_and_prepare_for_remeshing;
 
     /**
      * Callback to interpolate vectors and perform mesh adaption.
diff --git a/include/deal.II/lac/petsc_ts.templates.h b/include/deal.II/lac/petsc_ts.templates.h
index aea7f2951f..6a22574237 100644
--- a/include/deal.II/lac/petsc_ts.templates.h
+++ b/include/deal.II/lac/petsc_ts.templates.h
@@ -442,7 +442,14 @@ namespace PETScWrappers
 
       const int lineno = __LINE__;
       const int err    = call_and_possibly_capture_ts_exception(
-        user->decide_for_coarsening_and_refinement,
+        (user->decide_and_prepare_for_remeshing ?
+              [&](const real_type    t,
+               const unsigned int step,
+               const VectorType  &y,
+               bool              &resize) {
+             resize = user->decide_and_prepare_for_remeshing(t, step, y);
+           } :
+              user->decide_for_coarsening_and_refinement),
         user->pending_exception,
         {},
         t,
@@ -454,7 +461,7 @@ namespace PETScWrappers
         return PetscError(
           PetscObjectComm((PetscObject)ts),
           lineno + 1,
-          "decide_for_coarsening_and_refinement",
+          "decide_and_prepare_for_remeshing",
           __FILE__,
           PETSC_ERR_LIB,
           PETSC_ERROR_INITIAL,
@@ -1033,8 +1040,18 @@ namespace PETScWrappers
       AssertPETSc(TSMonitorSet(ts, ts_monitor, this, nullptr));
 
     // Handle AMR.
-    if (decide_for_coarsening_and_refinement)
+    if (decide_and_prepare_for_remeshing ||
+        decide_for_coarsening_and_refinement)
       {
+        if (decide_and_prepare_for_remeshing)
+          Assert(
+            !decide_for_coarsening_and_refinement,
+            ExcMessage(
+              "The 'decide_for_coarsening_and_refinement' callback name "
+              "of the TimeStepper class is deprecated. If you are setting "
+              "the equivalent 'decide_and_prepare_for_remeshing' callback, you "
+              "cannot also set the 'decide_for_coarsening_and_refinement' "
+              "callback."));
         AssertThrow(interpolate,
                     StandardExceptions::ExcFunctionNotProvided("interpolate"));
 #  if DEAL_II_PETSC_VERSION_GTE(3, 21, 0)