KINSOL: allow for custom setup

include/deal.II/sundials/kinsol.h

@@ -618,6 +618,30 @@ namespace SUNDIALS
      */
     std::function<VectorType &()> get_function_scaling;
 
+
+    /**
+     * A function object that users may supply and which is intended to perform
+     * custom setup on the supplied @p kinsol_mem object. Refer to the
+     * SUNDIALS documentation for valid options.
+     *
+     * For instance, the following code attaches a files for error output of the
+     * internal KINSOL implementation:
+     *
+     * @code
+     *      ode.custom_setup = [&](void *arkode_mem) {
+     *        KINSetErrFile(arkode_mem, errfile);
+     *      };
+     * @endcode
+     *
+     * @note This function will be called at the end of all other set up right
+     *   before the actual solve call is issued to KINSOL. Consult the SUNDIALS
+     *   manual to see which options are still available at this point.
+     *
+     * @param kinsol_mem pointer to the KINSOL memory block which can be used
+     *   for custom calls to `KINSet...` functions.
+     */
+    std::function<void(void *kinsol_mem)> custom_setup;
+
     /**
      * Handle KINSOL exceptions.
      */

source/sundials/kinsol.cc

@@ -451,6 +451,18 @@ namespace SUNDIALS
         AssertKINSOL(status);
       }
 
+    // Right before calling the main KINSol() call, allow expert users to
+    // perform additional setup operations on the KINSOL object.
+    if (custom_setup)
+      {
+        status =
+          Utilities::call_and_possibly_capture_exception(custom_setup,
+                                                         pending_exception,
+                                                         kinsol_mem);
+        AssertKINSOL(status);
+      }
+
+
     // Having set up all of the ancillary things, finally call the main KINSol
     // function. One we return, check that what happened:
     // - If we have a pending recoverable exception, ignore it if SUNDIAL's

tests/sundials/kinsol_05.cc

@@ -49,6 +49,26 @@
 // function, which has the current iterate. But it converges slowly
 // because it doesn't update the Jacobian very often. This test
 // finally updates it in every iteration.
+//
+// In addition, this test checks that an optional custom_setup callback is
+// called correctly.
+
+namespace
+{
+  /**
+   * Callback to test whether KINSOL::custom_setup() works.
+   */
+  void
+  kinsol_info_callback(const char *module,
+                       const char *function,
+                       char *      msg,
+                       void *      ih_data)
+  {
+    (void)ih_data;
+    deallog << "KINSOL info: " << module << ":" << function << ": " << msg
+            << std::endl;
+  }
+} // namespace
 
 int
 main()
@@ -121,6 +141,12 @@ main()
       J_inverse.vmult(dst, rhs);
     };
 
+  kinsol.custom_setup = [](void *kinsol_mem) {
+    // test custom_setup callback by querying some information from KINSOL
+    KINSetInfoHandlerFn(kinsol_mem, kinsol_info_callback, nullptr);
+    KINSetPrintLevel(kinsol_mem, 1);
+  };
+
   VectorType v(N);
   v(0) = 0.5;
   v(1) = 1.234;

tests/sundials/kinsol_05.output

@@ -1,20 +1,27 @@
 
+DEAL::KINSOL info: KINSOL:KINSolInit: scsteptol =     3.67e-11  fnormtol =     6.06e-06
 DEAL::Evaluating the solution at u=(0.500000,1.23400)
+DEAL::KINSOL info: KINSOL:KINSolInit: nni =    0   nfe =      1   fnorm =          1.805480887742806
 DEAL::Setting up Jacobian system at u=(0.500000,1.23400)
 DEAL::Solving Jacobian system with rhs=(0.162480,-1.79816)
 DEAL::Evaluating the solution at u=(0.500000,1.23400)
 DEAL::Evaluating the solution at u=(-0.282294,0.265967)
+DEAL::KINSOL info: KINSOL:KINSol: nni =    1   nfe =      2   fnorm =         0.5648238454047571
 DEAL::Setting up Jacobian system at u=(-0.282294,0.265967)
 DEAL::Solving Jacobian system with rhs=(0.564722,-0.0107297)
 DEAL::Evaluating the solution at u=(-0.282294,0.265967)
 DEAL::Evaluating the solution at u=(-0.000445202,0.0468183)
+DEAL::KINSOL info: KINSOL:KINSol: nni =    2   nfe =      3   fnorm =        0.04643227263854082
 DEAL::Setting up Jacobian system at u=(-0.000445202,0.0468183)
 DEAL::Solving Jacobian system with rhs=(0.00196544,-0.0463907)
 DEAL::Evaluating the solution at u=(-0.000445202,0.0468183)
 DEAL::Evaluating the solution at u=(-0.000536539,0.000570488)
+DEAL::KINSOL info: KINSOL:KINSol: nni =    3   nfe =      4   fnorm =       0.001073616152656229
 DEAL::Setting up Jacobian system at u=(-0.000536539,0.000570488)
 DEAL::Solving Jacobian system with rhs=(0.00107308,-3.39491e-05)
 DEAL::Evaluating the solution at u=(-0.000536554,0.000570504)
 DEAL::Evaluating the solution at u=(-2.88123e-10,7.40347e-10)
+DEAL::KINSOL info: KINSOL:KINSol: nni =    4   nfe =      5   fnorm =      7.325069237808057e-10
+DEAL::KINSOL info: KINSOL:KINSol: Return value: 0 (KIN_SUCCESS)
 -2.881e-10 7.403e-10 
 DEAL::Converged in 4 iterations.