Debian Codegraph @

include/deal.II/sundials/kinsol.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2017 - 2025 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15
16 #ifndef dealii_sundials_kinsol_h
17 #define dealii_sundials_kinsol_h
18
19 #include <deal.II/base/config.h>
20
21 #ifdef DEAL_II_WITH_SUNDIALS
22
23
24 # include <deal.II/base/conditional_ostream.h>
25 # include <deal.II/base/exceptions.h>
26 # include <deal.II/base/mpi_stub.h>
27 # include <deal.II/base/parameter_handler.h>
28
29 # include <deal.II/lac/vector.h>
30 # include <deal.II/lac/vector_memory.h>
31
32 # include <deal.II/sundials/sundials_types.h>
33
34 # include <boost/signals2.hpp>
35
36 # include <kinsol/kinsol.h>
37 # include <nvector/nvector_serial.h>
38 # include <sundials/sundials_math.h>
39
40 # include <exception>
41 # include <memory>
42
43
44 DEAL_II_NAMESPACE_OPEN
45
46
47 namespace SUNDIALS
48 {
49 /**
50 * Interface to SUNDIALS' nonlinear solver (KINSOL).
51 *
52 * KINSOL is a solver for nonlinear algebraic systems in residual form $F(u)
53 * = 0$ or fixed point form $G(u) = u$, where $u$ is a vector which we will
54 * assume to be in ${\mathbb R}^n$ or ${\mathbb C}^n$, but that may also have
55 * a block structure and may be distributed in parallel computations; the
56 * functions $F$ and $G$ satisfy $F,G:{\mathbb R}^N \to{\mathbb R}^N$ or
57 * $F,G:{\mathbb C}^N \to{\mathbb C}^N$. It includes a Newton-Krylov solver
58 * as well as Picard and fixed point solvers, both of which can be
59 * accelerated with Anderson acceleration. KINSOL is based on the previous
60 * Fortran package NKSOL of Brown and Saad. An example of using KINSOL
61 * can be found in the step-77 tutorial program.
62 *
63 * KINSOL's Newton solver employs the inexact Newton method. As this solver
64 * is intended mainly for large systems, the user is required to provide
65 * their own solver function.
66 *
67 * At the highest level, KINSOL implements the following iteration
68 * scheme:
69 * - set $u_0$ = an initial guess
70 * - For $n = 0, 1, 2, \ldots$ until convergence do:
71 * - Solve $J(u_n)\delta_n = -F(u_n)$
72 * - Set $u_{n+1} = u_n + \lambda \delta_n, 0 < \lambda \leq 1$
73 * - Test for convergence
74 *
75 * Here, $u_n$ is the $n$-th iterate to $u$, and $J(u) = \nabla_u F(u)$ is
76 * the system Jacobian. At each stage in the iteration process, a scalar
77 * multiple of the step $\delta_n$, is added to $u_n$ to produce a new
78 * iterate, $u_{n+1}$. A test for convergence is made before the iteration
79 * continues.
80 *
81 * Unless specified otherwise by the user, KINSOL strives to update Jacobian
82 * information as infrequently as possible to balance the high costs of
83 * matrix operations against other costs. Specifically, these updates occur
84 * when:
85 * - the problem is initialized,
86 * - $\|\lambda \delta_{n-1} \|_{D_u,\infty} \geq 1.5$ (inexact Newton only,
87 * see below for a definition of $\| \cdot \|_{D_u,\infty}$)
88 * - a specified number of nonlinear iterations have passed since the last
89 * update,
90 * - the linear solver failed recoverably with outdated Jacobian information,
91 * - the global strategy failed with outdated Jacobian information, or
92 * - $\|\lambda \delta_{n} \|_{D_u,\infty} \leq $ *tolerance* with outdated
93 * Jacobian information.
94 *
95 * KINSOL allows changes to the above strategy through optional solver
96 * inputs. The user can disable the initial Jacobian information evaluation
97 * or change the default value of the number of nonlinear iterations after
98 * which a Jacobian information update is enforced.
99 *
100 * To address the case of ill-conditioned nonlinear systems, KINSOL allows
101 * prescribing scaling factors both for the solution vector and for the
102 * residual vector. For scaling to be used, the user may supply the function
103 * get_solution_scaling(), that returns values $D_u$, which are diagonal
104 * elements of the scaling matrix such that $D_u u_n$ has all components
105 * roughly the same magnitude when $u_n$ is close to a solution, and
106 * get_function_scaling(), that supply values $D_F$, which are diagonal
107 * scaling matrix elements such that $D_F F$ has all components roughly the
108 * same magnitude when $u_n$ is *not* too close to a solution.
109 *
110 * When scaling values are provided for the solution vector, these values are
111 * automatically incorporated into the calculation of the perturbations used
112 * for the default difference quotient approximations for Jacobian
113 * information if the user does not supply a Jacobian solver through the
114 * solve_with_jacobian() function.
115 *
116 * Two methods of applying a computed step $\delta_n$ to the previously
117 * computed solution vector are implemented. The first and simplest is the
118 * standard Newton strategy which applies the update with a constant
119 * $\lambda$ always set to 1. The other method is a global strategy, which
120 * attempts to use the direction implied by $\delta_n$ in the most efficient
121 * way for furthering convergence of the nonlinear problem. This technique is
122 * implemented in the second strategy, called Linesearch. This option employs
123 * both the $\alpha$ and $\beta$ conditions of the Goldstein-Armijo
124 * linesearch algorithm given in @cite DennisSchnabel96 ,
125 * where $\lambda$ is chosen to guarantee a sufficient
126 * decrease in $F$ relative to the step length as well as a minimum step
127 * length relative to the initial rate of decrease of $F$. One property of the
128 * algorithm is that the full Newton step tends to be taken close to the
129 * solution.
130 *
131 * The basic fixed-point iteration scheme implemented in KINSOL is given by:
132 * - Set $u_0 =$ an initial guess
133 * - For $n = 0, 1, 2, \dots$ until convergence do:
134 * - Set $u_{n+1} = G(u_n)$
135 * - Test for convergence
136 *
137 * At each stage in the iteration process, function $G$ is applied to the
138 * current iterate to produce a new iterate, $u_{n+1}$. A test for
139 * convergence is made before the iteration continues.
140 *
141 * For Picard iteration, as implemented in KINSOL, we consider a special form
142 * of the nonlinear function $F$, such that $F(u) = Lu - N(u)$, where $L$ is
143 * a constant nonsingular matrix and $N$ is (in general) nonlinear.
144 *
145 * Then the fixed-point function $G$ is defined as $G(u) = u - L^{-1}F(u)$.
146 * Within each iteration, the Picard step is computed then added to $u_n$ to
147 * produce the new iterate. Next, the nonlinear residual function is
148 * evaluated at the new iterate, and convergence is checked. The Picard and
149 * fixed point methods can be significantly accelerated using Anderson's
150 * acceleration method.
151 *
152 * The user has to provide the implementation of the following
153 * `std::function`s:
154 * - reinit_vector;
155 * and only one of
156 * - residual;
157 * or
158 * - iteration_function;
159 *
160 * Specifying residual() allows the user to use Newton and Picard strategies
161 * (i.e., $F(u)=0$ will be solved), while specifying iteration_function(), a
162 * fixed point iteration will be used (i.e., $G(u)=u$ will be solved). An
163 * error will be thrown if iteration_function() is set for Picard or
164 * Newton.
165 *
166 * If the use of a Newton or Picard method is desired, then the user should
167 * also supply
168 * - solve_with_jacobian;
169 * and optionally
170 * - setup_jacobian;
171 *
172 * Fixed point iteration does not require the solution of any linear system.
173 *
174 * Also the following functions could be rewritten, to provide additional
175 * scaling factors for both the solution and the residual evaluation during
176 * convergence checks:
177 * - get_solution_scaling;
178 * - get_function_scaling.
179 */
180 template <typename VectorType = Vector<double>>
181 class KINSOL
182 {
183 public:
184 /**
185 * Additional parameters that can be passed to the KINSOL class.
186 */
187 class AdditionalData
188 {
189 public:
190 /**
191 * KINSOL solution strategy. KINSOL includes a Newton-Krylov solver (both
192 * local and global) as well as Picard and fixed point solvers.
193 */
194 enum SolutionStrategy
195 {
196 /**
197 * Standard Newton iteration.
198 */
199 newton = KIN_NONE,
200 /**
201 * Newton iteration with linesearch.
202 */
203 linesearch = KIN_LINESEARCH,
204 /**
205 * Fixed point iteration.
206 */
207 fixed_point = KIN_FP,
208 /**
209 * Picard iteration.
210 */
211 picard = KIN_PICARD,
212 };
213
214
215 /**
216 * Orthogonalization strategy used for fixed-point iteration with
217 * Anderson acceleration. While `modified_gram_schmidt` is a good default
218 * choice, it suffers from excessive communication for a growing number of
219 * acceleration vectors. Instead, the user may use one of the other
220 * strategies. For a detailed documentation consult the SUNDIALS manual.
221 *
222 * @note Similar strategies are defined in
223 * LinearAlgebra::OrthogonalizationStrategy.
224 *
225 * @note The values assigned to the enum constants matter since they are
226 * directly passed to KINSOL.
227 */
228 enum OrthogonalizationStrategy
229 {
230 /**
231 * The default, stable strategy. Requires an increasing number of
232 * communication steps with increasing Anderson subspace size.
233 */
234 modified_gram_schmidt = 0,
235
236 /**
237 * Use a compact WY representation in the orthogonalization process of
238 * the inverse iteration with the Householder transformation. This
239 * strategy requires two communication steps and a very small linear
240 * system solve.
241 */
242 inverse_compact = 1,
243
244 /**
245 * Classical Gram Schmidt, that can work on multi-vectors in parallel
246 * and thus always requires three communication steps. However, it
247 * is less stable in terms of roundoff error propagation, requiring
248 * additional re-orthogonalization steps more frequently.
249 */
250 classical_gram_schmidt = 2,
251
252 /**
253 * Classical Gram Schmidt with delayed re-orthogonalization, which
254 * reduces the number of communication steps from three to two compared
255 * to `classical_gram_schmidt`.
256 */
257 delayed_classical_gram_schmidt = 3,
258 };
259
260 /**
261 * Initialization parameters for KINSOL.
262 *
263 * Global parameters:
264 *
265 * @param strategy Solution strategy
266 * @param maximum_non_linear_iterations Maximum number of nonlinear
267 * iterations
268 * @param function_tolerance %Function norm stopping tolerance
269 * @param step_tolerance Scaled step stopping tolerance
270 *
271 * Newton parameters:
272 *
273 * @param no_init_setup No initial matrix setup
274 * @param maximum_setup_calls Maximum iterations without matrix setup
275 * @param maximum_newton_step Maximum allowable scaled length of the
276 * Newton step
277 * @param dq_relative_error Relative error for different quotient
278 * computation
279 *
280 * Line search parameters:
281 *
282 * @param maximum_beta_failures Maximum number of beta-condition failures
283 *
284 * Fixed point and Picard parameters:
285 *
286 * @param anderson_subspace_size Anderson acceleration subspace size
287 * @param anderson_qr_orthogonalization Orthogonalization strategy for QR
288 * factorization when using Anderson acceleration
289 */
290 AdditionalData(const SolutionStrategy &strategy = linesearch,
291 const unsigned int maximum_non_linear_iterations = 200,
292 const double function_tolerance = 0.0,
293 const double step_tolerance = 0.0,
294 const bool no_init_setup = false,
295 const unsigned int maximum_setup_calls = 0,
296 const double maximum_newton_step = 0.0,
297 const double dq_relative_error = 0.0,
298 const unsigned int maximum_beta_failures = 0,
299 const unsigned int anderson_subspace_size = 0,
300 const OrthogonalizationStrategy
301 anderson_qr_orthogonalization = modified_gram_schmidt);
302
303 /**
304 * Add all AdditionalData() parameters to the given ParameterHandler
305 * object. When the parameters are parsed from a file, the internal
306 * parameters are automatically updated.
307 *
308 * The following parameters are declared:
309 *
310 * @code
311 * set Function norm stopping tolerance = 0
312 * set Maximum number of nonlinear iterations = 200
313 * set Scaled step stopping tolerance = 0
314 * set Solution strategy = linesearch
315 * subsection Fixed point and Picard parameters
316 * set Anderson acceleration subspace size = 5
317 * end
318 * subsection Linesearch parameters
319 * set Maximum number of beta-condition failures = 0
320 * end
321 * subsection Newton parameters
322 * set Maximum allowable scaled length of the Newton step = 0
323 * set Maximum iterations without matrix setup = 0
324 * set No initial matrix setup = false
325 * set Relative error for different quotient computation = 0
326 * end
327 * @endcode
328 *
329 * These are one-to-one with the options you can pass at construction
330 * time.
331 *
332 * The options you pass at construction time are set as default values in
333 * the ParameterHandler object `prm`. You can later modify them by parsing
334 * a parameter file using `prm`. The values of the parameter will be
335 * updated whenever the content of `prm` is updated.
336 *
337 * Make sure that this class lives longer than `prm`. Undefined behavior
338 * will occur if you destroy this class, and then parse a parameter file
339 * using `prm`.
340 */
341 void
342 add_parameters(ParameterHandler &prm);
343
344 /**
345 * The solution strategy to use. If you choose SolutionStrategy::newton,
346 * SolutionStrategy::linesearch, or SolutionStrategy::picard you have to
347 * provide the function residual(). If you choose
348 * SolutionStrategy::fixed_point, you have to provide the function
349 * iteration_function().
350 */
351 SolutionStrategy strategy;
352
353 /**
354 * Maximum number of nonlinear iterations allowed.
355 */
356 unsigned int maximum_non_linear_iterations;
357
358 /**
359 * A scalar used as a stopping tolerance on the scaled
360 * maximum norm of the system function $F(u)$ or $G(u)$.
361 *
362 * If set to zero, default values provided by KINSOL will be used.
363 */
364 double function_tolerance;
365
366 /**
367 * A scalar used as a stopping tolerance on the minimum
368 * scaled step length.
369 *
370 * If set to zero, default values provided by KINSOL will be used.
371 */
372 double step_tolerance;
373
374 /**
375 * Whether an initial call to the preconditioner or Jacobian
376 * setup function should be made or not.
377 *
378 * A call to this function is useful when solving a sequence of problems,
379 * in which the final preconditioner or Jacobian value from one problem
380 * is to be used initially for the next problem.
381 */
382 bool no_init_setup;
383
384 /**
385 * The maximum number of nonlinear iterations that can be
386 * performed between calls to the setup_jacobian() function.
387 *
388 * If set to zero, default values provided by KINSOL will be used,
389 * and in practice this often means that KINSOL will re-use a
390 * Jacobian matrix computed in one iteration for later iterations.
391 */
392 unsigned int maximum_setup_calls;
393
394 /**
395 * The maximum allowable scaled length of the Newton step.
396 *
397 * If set to zero, default values provided by KINSOL will be used.
398 */
399 double maximum_newton_step;
400
401 /**
402 * The relative error in computing $F(u)$, which is used in the
403 * difference quotient approximation to the Jacobian matrix when the user
404 * does not supply a solve_with_jacobian() function.
405 *
406 * If set to zero, default values provided by KINSOL will be used.
407 */
408 double dq_relative_error;
409
410 /**
411 * The maximum number of beta-condition failures in the
412 * linesearch algorithm. Only used if
413 * strategy==SolutionStrategy::linesearch.
414 */
415 unsigned int maximum_beta_failures;
416
417 /**
418 * The size of the subspace used with Anderson acceleration
419 * in conjunction with Picard or fixed-point iteration.
420 *
421 * If you set this to 0, no acceleration is used.
422 */
423 unsigned int anderson_subspace_size;
424
425 /**
426 * In case Anderson acceleration is used, this parameter selects the
427 * orthogonalization strategy used in the QR factorization.
428 */
429 OrthogonalizationStrategy anderson_qr_orthogonalization;
430 };
431
432 /**
433 * Constructor, with class parameters set by the AdditionalData object.
434 *
435 * @param data KINSOL configuration data
436 *
437 * @note With SUNDIALS 6 and later this constructor sets up logging
438 * objects to only work on the present processor (i.e., results are only
439 * communicated over MPI_COMM_SELF).
440 */
441 KINSOL(const AdditionalData &data = AdditionalData());
442
443 /**
444 * Constructor.
445 *
446 * @param data KINSOL configuration data
447 * @param mpi_comm MPI Communicator over which logging operations are
448 * computed. Only used in SUNDIALS 6 and newer.
449 */
450 KINSOL(const AdditionalData &data, const MPI_Comm mpi_comm);
451
452 /**
453 * Destructor.
454 */
455 ~KINSOL();
456
457 /**
458 * Solve the non linear system. Return the number of nonlinear steps taken
459 * to converge. KINSOL uses the content of `initial_guess_and_solution` as
460 * initial guess, and stores the final solution in the same vector.
461 */
462 unsigned int
463 solve(VectorType &initial_guess_and_solution);
464
465 /**
466 * A function object that users need to supply and that is intended to
467 * reinitize the given vector to its correct size, block structure (if
468 * block vectors are used), and MPI communicator (if the vector is
469 * distributed across multiple processors using MPI), along with any
470 * other properties necessary.
471 *
472 * @note This variable represents a
473 * @ref GlossUserProvidedCallBack "user provided callback".
474 * See there for a description of how to deal with errors and other
475 * requirements and conventions. In particular, KINSOL can deal
476 * with "recoverable" errors in some circumstances, so callbacks
477 * can throw exceptions of type RecoverableUserCallbackError.
478 */
479 std::function<void(VectorType &)> reinit_vector;
480
481 /**
482 * A function object that users should supply and that is intended to
483 * compute the residual `dst = F(src)`. This function is only used if the
484 * SolutionStrategy::newton, SolutionStrategy::linesearch, or
485 * SolutionStrategy::picard strategies were selected.
486 *
487 * @note This variable represents a
488 * @ref GlossUserProvidedCallBack "user provided callback".
489 * See there for a description of how to deal with errors and other
490 * requirements and conventions. In particular, KINSOL can deal
491 * with "recoverable" errors in some circumstances, so callbacks
492 * can throw exceptions of type RecoverableUserCallbackError.
493 */
494 std::function<void(const VectorType &src, VectorType &dst)> residual;
495
496 /**
497 * A function object that users should supply and that is intended to
498 * compute the iteration function $G(u)$ for the fixed point
499 * iteration. This function is only used if the
500 * SolutionStrategy::fixed_point strategy is selected.
501 *
502 * @note This variable represents a
503 * @ref GlossUserProvidedCallBack "user provided callback".
504 * See there for a description of how to deal with errors and other
505 * requirements and conventions. In particular, KINSOL can deal
506 * with "recoverable" errors in some circumstances, so callbacks
507 * can throw exceptions of type RecoverableUserCallbackError.
508 */
509 std::function<void(const VectorType &src, VectorType &dst)>
510 iteration_function;
511
512 /**
513 * A function object that users may supply and that is intended to
514 * prepare the linear solver for subsequent calls to
515 * solve_with_jacobian().
516 *
517 * The job of setup_jacobian() is to prepare the linear solver for
518 * subsequent calls to solve_with_jacobian(), in the solution of linear
519 * systems $Ax = b$. The exact nature of this system depends on the
520 * SolutionStrategy that has been selected.
521 *
522 * In the cases strategy = SolutionStrategy::newton or
523 * SolutionStrategy::linesearch, $A$ is the Jacobian $J = \partial
524 * F/\partial u$. If strategy = SolutionStrategy::picard, $A$ is the
525 * approximate Jacobian matrix $L$. If strategy =
526 * SolutionStrategy::fixed_point, then linear systems do not arise, and this
527 * function is never called.
528 *
529 * The setup_jacobian() function may call a user-supplied function, or a
530 * function within the linear solver group, to compute Jacobian-related
531 * data that is required by the linear solver. It may also preprocess that
532 * data as needed for solve_with_jacobian(), which may involve calling a
533 * generic function (such as for LU factorization) or, more generally,
534 * build preconditioners from the assembled Jacobian. In any case, the
535 * data so generated may then be used whenever a linear system is solved.
536 *
537 * The point of this function is that
538 * setup_jacobian() function is not called at every Newton iteration,
539 * but only as frequently as the solver determines that it is appropriate
540 * to perform the setup task. In this way, Jacobian-related data generated
541 * by setup_jacobian() is expected to be used over a number of Newton
542 * iterations. KINSOL determines itself when it is beneficial to regenerate
543 * the Jacobian and associated information (such as preconditioners
544 * computed for the Jacobian), thereby saving the effort to regenerate
545 * the Jacobian matrix and a preconditioner for it whenever possible.
546 *
547 * @param current_u Current value of $u$
548 * @param current_f Current value of $F(u)$ or $G(u)$
549 *
550 * @note This variable represents a
551 * @ref GlossUserProvidedCallBack "user provided callback".
552 * See there for a description of how to deal with errors and other
553 * requirements and conventions. In particular, KINSOL can deal
554 * with "recoverable" errors in some circumstances, so callbacks
555 * can throw exceptions of type RecoverableUserCallbackError.
556 */
557 std::function<void(const VectorType &current_u,
558 const VectorType &current_f)>
559 setup_jacobian;
560
561 /**
562 * A function object that users may supply and that is intended to solve
563 * a linear system with the Jacobian matrix. This function will be called by
564 * KINSOL (possibly several times) after setup_jacobian() has been called at
565 * least once. KINSOL tries to do its best to call setup_jacobian() the
566 * minimum number of times. If convergence can be achieved without updating
567 * the Jacobian, then KINSOL does not call setup_jacobian() again. If, on
568 * the contrary, internal KINSOL convergence tests fail, then KINSOL calls
569 * setup_jacobian() again with updated vectors and coefficients so that
570 * successive calls to solve_with_jacobian() lead to better convergence
571 * in the Newton process.
572 *
573 * If you do not specify a `solve_with_jacobian` function, then only a
574 * fixed point iteration strategy can be used. Notice that this may not
575 * converge, or may converge very slowly.
576 *
577 * A call to this function should store in `dst` the result of $J^{-1}$
578 * applied to `rhs`, i.e., $J \cdot dst = rhs$. It is the user's
579 * responsibility to set up proper solvers and preconditioners inside this
580 * function (or in the `setup_jacobian` callback above). The function
581 * attached to this callback is also provided with a tolerance to the linear
582 * solver, indicating that it is not necessary to solve the linear system
583 * with the Jacobian matrix exactly, but only to a tolerance that KINSOL
584 * will adapt over time.
585 *
586 * Arguments to the function are:
587 *
588 * @param[in] rhs The system right hand side to solve for.
589 * @param[out] dst The solution of $J^{-1} * src$.
590 * @param[in] tolerance The tolerance with which to solve the linear system
591 * of equations.
592 *
593 * @note This variable represents a
594 * @ref GlossUserProvidedCallBack "user provided callback".
595 * See there for a description of how to deal with errors and other
596 * requirements and conventions. In particular, KINSOL can deal
597 * with "recoverable" errors in some circumstances, so callbacks
598 * can throw exceptions of type RecoverableUserCallbackError.
599 */
600 std::function<
601 void(const VectorType &rhs, VectorType &dst, const double tolerance)>
602 solve_with_jacobian;
603
604 /**
605 * A function object that users may supply and that is intended to return a
606 * vector whose components are the weights used by KINSOL to compute the
607 * vector norm of the solution. The implementation of this function is
608 * optional, and it is used only if implemented.
609 *
610 * The intent for this scaling factor is for problems in which the different
611 * components of a solution have vastly different numerical magnitudes --
612 * typically because they have different physical units and represent
613 * different things. For example, if one were to solve a nonlinear Stokes
614 * problem, the solution vector has components that correspond to velocities
615 * and other components that correspond to pressures. These have different
616 * physical units and depending on which units one chooses, they may have
617 * roughly comparable numerical sizes or maybe they don't. To give just one
618 * example, in simulations of flow in the Earth's interior, one has
619 * velocities on the order of maybe ten centimeters per year, and pressures
620 * up to around 100 GPa. If one expresses this in SI units, this corresponds
621 * to velocities of around $0.000,000,003=3 \times 10^{-9}$ m/s, and
622 * pressures around $10^9 \text{kg}/\text{m}/\text{s}^2$, i.e., vastly
623 * different. In such cases, computing the $l_2$ norm of a solution-type
624 * vector (e.g., the difference between the previous and the current
625 * solution) makes no sense because the norm will either be dominated by the
626 * velocity components or the pressure components. The scaling vector this
627 * function returns is intended to provide each component of the solution
628 * with a scaling factor that is generally chosen as the inverse of a
629 * "typical velocity" or "typical pressure" so that upon multiplication of a
630 * vector component by the corresponding scaling vector component, one
631 * obtains a number that is of order of magnitude of one (i.e., a reasonably
632 * small multiple of one times the typical velocity/pressure). The KINSOL
633 * manual states this as follows: "The user should supply values $D_u$,
634 * which are diagonal elements of the scaling matrix such that $D_u U$ has
635 * all components roughly the same magnitude when $U$ is close to a
636 * solution".
637 *
638 * If no function is provided to a KINSOL object, then this is interpreted
639 * as implicitly saying that all of these scaling factors should be
640 * considered as one.
641 *
642 * @note This variable represents a
643 * @ref GlossUserProvidedCallBack "user provided callback".
644 * See there for a description of how to deal with errors and other
645 * requirements and conventions. In particular, KINSOL can deal
646 * with "recoverable" errors in some circumstances, so callbacks
647 * can throw exceptions of type RecoverableUserCallbackError.
648 */
649 std::function<VectorType &()> get_solution_scaling;
650
651 /**
652 * A function object that users may supply and that is intended to return a
653 * vector whose components are the weights used by KINSOL to compute the
654 * vector norm of the function evaluation away from the solution. The
655 * implementation of this function is optional, and it is used only if
656 * implemented.
657 *
658 * The point of this function and the scaling vector it returns is similar
659 * to the one discussed above for `get_solution_scaling`, except that it is
660 * for a vector that scales the components of the function $F(U)$, rather
661 * than the components of $U$, when computing norms. As above, if no
662 * function is provided, then this is equivalent to using a scaling vector
663 * whose components are all equal to one.
664 *
665 * @note This variable represents a
666 * @ref GlossUserProvidedCallBack "user provided callback".
667 * See there for a description of how to deal with errors and other
668 * requirements and conventions. In particular, KINSOL can deal
669 * with "recoverable" errors in some circumstances, so callbacks
670 * can throw exceptions of type RecoverableUserCallbackError.
671 */
672 std::function<VectorType &()> get_function_scaling;
673
674
675 /**
676 * A function object that users may supply and which is intended to perform
677 * custom setup on the supplied @p kinsol_mem object. Refer to the
678 * SUNDIALS documentation for valid options.
679 *
680 * For instance, the following code attaches a file for error output of the
681 * internal KINSOL implementation:
682 *
683 * @code
684 * // Open C-style file handle and manage it inside a shared_ptr which
685 * // is handed to the lambda capture in the next statement. When the
686 * // custom_setup function is destroyed, the file is closed.
687 * auto errfile = std::shared_ptr<FILE>(
688 * fopen("kinsol.err", "w"),
689 * [](FILE *fptr) { fclose(fptr); });
690 *
691 * ode.custom_setup = [&, errfile](void *kinsol_mem) {
692 * KINSetErrFile(kinsol_mem, errfile.get());
693 * };
694 * @endcode
695 *
696 * @note This function will be called at the end of all other setup code
697 * right before the actual solve call is issued to KINSOL. Consult the
698 * SUNDIALS manual to see which options are still available at this point.
699 *
700 * @param kinsol_mem pointer to the KINSOL memory block which can be used
701 * for custom calls to `KINSet...` functions.
702 */
703 std::function<void(void *kinsol_mem)> custom_setup;
704
705 /**
706 * Handle KINSOL exceptions.
707 */
708 DeclException1(ExcKINSOLError,
709 int,
710 << "One of the SUNDIALS KINSOL internal functions "
711 << "returned a negative error code: " << arg1
712 << ". Please consult SUNDIALS manual.");
713
714 private:
715 /**
716 * Throw an exception when a function with the given name is not
717 * implemented.
718 */
719 DeclException1(ExcFunctionNotProvided,
720 std::string,
721 << "Please provide an implementation for the function \""
722 << arg1 << "\"");
723
724 /**
725 * This function is executed at construction time to set the
726 * std::function above to trigger an assert if they are not
727 * implemented.
728 */
729 void
730 set_functions_to_trigger_an_assert();
731
732 /**
733 * KINSOL configuration data.
734 */
735 AdditionalData data;
736
737 /**
738 * The MPI communicator to be used by this solver, if any.
739 */
740 MPI_Comm mpi_communicator;
741
742 /**
743 * KINSOL memory object.
744 */
745 void *kinsol_mem;
746
747 # if DEAL_II_SUNDIALS_VERSION_GTE(6, 0, 0)
748 /**
749 * A context object associated with the KINSOL solver.
750 */
751 SUNContext kinsol_ctx;
752 # endif
753
754
755 /**
756 * Memory pool of vectors.
757 */
758 GrowingVectorMemory<VectorType> mem;
759
760 /**
761 * A pointer to any exception that may have been thrown in user-defined
762 * call-backs and that we have to deal after the KINSOL function we call
763 * has returned.
764 */
765 mutable std::exception_ptr pending_exception;
766 };
767
768 } // namespace SUNDIALS
769
770
771 DEAL_II_NAMESPACE_CLOSE
772
773 #else
774
775 // Make sure the scripts that create the C++20 module input files have
776 // something to latch on if the preprocessor #ifdef above would
777 // otherwise lead to an empty content of the file.
778 DEAL_II_NAMESPACE_OPEN
779 DEAL_II_NAMESPACE_CLOSE
780
781 #endif
782
783 #endif