Debian Codegraph @

include/deal.II/sundials/ida.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_ida_h
17 #define dealii_sundials_ida_h
18
19 #include <deal.II/base/config.h>
20
21 #ifdef DEAL_II_WITH_SUNDIALS
22 # include <deal.II/base/conditional_ostream.h>
23 # include <deal.II/base/exceptions.h>
24 # include <deal.II/base/mpi_stub.h>
25 # include <deal.II/base/parameter_handler.h>
26
27 # ifdef DEAL_II_WITH_PETSC
28 # include <deal.II/lac/petsc_block_vector.h>
29 # include <deal.II/lac/petsc_vector.h>
30 # endif
31 # include <deal.II/lac/vector.h>
32 # include <deal.II/lac/vector_memory.h>
33
34 # ifdef DEAL_II_SUNDIALS_WITH_IDAS
35 # include <idas/idas.h>
36 # else
37 # include <ida/ida.h>
38 # endif
39
40 # include <deal.II/sundials/sundials_types.h>
41 # include <deal.II/sundials/sunlinsol_wrapper.h>
42
43 # include <boost/signals2.hpp>
44
45 # include <nvector/nvector_serial.h>
46 # include <sundials/sundials_config.h>
47 # include <sundials/sundials_math.h>
48
49 # include <memory>
50
51
52 DEAL_II_NAMESPACE_OPEN
53
54
55 namespace SUNDIALS
56 {
57 /**
58 * Interface to SUNDIALS Implicit Differential-Algebraic (IDA) solver.
59 *
60 * The class IDA is a wrapper to SUNDIALS Implicit Differential-Algebraic
61 * solver which is a general purpose solver for systems of
62 * Differential-Algebraic Equations (DAEs). Another class that can solve
63 * this set of equations is PETScWrappers::TimeStepper.
64 *
65 * The user has to provide the implementation of the following std::functions:
66 * - reinit_vector;
67 * - residual;
68 * - setup_jacobian;
69 * - solve_with_jacobian;
70 *
71 * Optionally, also the following functions could be provided. By default
72 * they do nothing, or are not required. If you call the constructor in a way
73 * that requires a not-implemented function, an Assertion will be
74 * thrown.
75 * - solver_should_restart;
76 * - differential_components;
77 * - get_local_tolerances;
78 *
79 * To output steps, connect a function to the signal
80 * - output_step;
81 *
82 * Citing from the SUNDIALS documentation:
83 *
84 * Consider a system of Differential-Algebraic Equations written in the
85 * general form
86 *
87 * \f[
88 * \begin{cases}
89 * F(t,y,\dot y) = 0\, , \\
90 * y(t_0) = y_0\, , \\
91 * \dot y (t_0) = \dot y_0\, .
92 * \end{cases}
93 * \f]
94 *
95 * where $y,\dot y$ are vectors in $\mathbb{R}^n$, $t$ is often the time (but
96 * can also be a parametric quantity), and
97 * $F:\mathbb{R}\times\mathbb{R}^n\times \mathbb{R}^n\rightarrow\mathbb{R}^n$.
98 * Such problem is solved using Newton iteration augmented with a line search
99 * global strategy. The integration method used in IDA is the variable-order,
100 * variable-coefficient BDF (Backward Differentiation Formula), in
101 * fixed-leading-coefficient. The method order ranges from 1 to 5, with
102 * the BDF of order $q$ given by the multistep formula
103 *
104 * \f[
105 * \sum_{i=0}^q \alpha_{n,i}\,y_{n-i}=h_n\,\dot y_n\, ,
106 * \label{eq:bdf}
107 * \f]
108 *
109 * where $y_n$ and $\dot y_n$ are the computed approximations of $y(t_n)$
110 * and $\dot y(t_n)$, respectively, and the step size is
111 * $h_n=t_n-t_{n-1}$. The coefficients $\alpha_{n,i}$ are uniquely
112 * determined by the order $q$, and the history of the step sizes. The
113 * application of the BDF method to the DAE system results in a nonlinear
114 *algebraic system to be solved at each time step:
115 *
116 * \f[
117 * G(y_n)\equiv F\left(t_n,y_n,\dfrac{1}{h_n}\sum_{i=0}^q
118 * \alpha_{n,i}\,y_{n-i}\right)=0\, .
119 * \f]
120 * The Newton method leads to a linear system of the form
121 * \f[
122 * J[y_{n(m+1)}-y_{n(m)}]=-G(y_{n(m)})\, ,
123 * \f]
124 *
125 *where $y_{n(m)}$ is the $m$-th approximation to $y_n$, and $J$ is the
126 *approximation of the system Jacobian
127 *
128 * \f[
129 * J=\dfrac{\partial G}{\partial y}
130 * = \dfrac{\partial F}{\partial y} +
131 * \alpha \dfrac{\partial F}{\partial \dot y}\, ,
132 * \f]
133 *
134 * and $\alpha = \alpha_{n,0}/h_n$. It is worth mentioning that the
135 * scalar $\alpha$ changes whenever the step size or method order
136 * changes.
137 *
138 *
139 * <h3> A simple example: an ordinary differential equation </h3>
140 *
141 * To provide a simple example, consider the following harmonic oscillator
142 * problem:
143 * \f[ \begin{split}
144 * u'' & = -k^2 u \\
145 * u (0) & = 0 \\
146 * u'(0) & = k
147 * \end{split}
148 * \f]
149 *
150 * We write it in terms of a first order ode:
151 *\f[
152 * \begin{matrix}
153 * y_0' & -y_1 & = 0 \\
154 * y_1' & + k^2 y_0 & = 0
155 * \end{matrix}
156 * \f]
157 *
158 * That is, $F(y', y, t) = y' + A y = 0 $
159 * where
160 * \f[
161 * A =
162 * \begin{pmatrix}
163 * 0 & -1 \\
164 * k^2 &0
165 * \end{pmatrix}
166 * \f]
167 * and $y(0)=(0, k)$, $y'(0) = (k, 0)$.
168 *
169 * The exact solution is $y_0(t) = \sin(k t)$, $y_1(t) = y_0'(t)
170 * = k \cos(k t)$, $y_1'(t) = -k^2 \sin(k t)$.
171 *
172 * The Jacobian to assemble is the following: $J = \alpha I + A$.
173 *
174 * This is achieved by the following snippet of code:
175 * @code
176 * using VectorType = Vector<double>;
177 *
178 * VectorType y(2);
179 * VectorType y_dot(2);
180 *
181 * double kappa = 1.0;
182 *
183 * FullMatrix<double> A(2,2);
184 * A(0,1) = -1.0;
185 * A(1,0) = kappa*kappa;
186 *
187 * FullMatrix<double> J(2,2);
188 * FullMatrix<double> Jinv(2,2);
189 *
190 * IDA time_stepper;
191 *
192 * time_stepper.reinit_vector = [&] (VectorType&v)
193 * {
194 * v.reinit(2);
195 * };
196 *
197 * time_stepper.residual = [&](const double t,
198 * const VectorType &y,
199 * const VectorType &y_dot,
200 * VectorType &res)
201 * {
202 * res = y_dot;
203 * A.vmult_add(res, y);
204 * };
205 *
206 * time_stepper.setup_jacobian = [&](const double ,
207 * const VectorType &, // y
208 * const VectorType &, // y_dot
209 * const double alpha)
210 * {
211 * J = A;
212 *
213 * J(0,0) += alpha;
214 * J(1,1) += alpha;
215 *
216 * Jinv.invert(J);
217 * };
218 *
219 * time_stepper.solve_with_jacobian_system = [&](const VectorType &src,
220 * VectorType &dst,
221 * const double) // tolerance
222 * {
223 * Jinv.vmult(dst,src);
224 * };
225 *
226 * y[1] = kappa;
227 * y_dot[0] = kappa;
228 * time_stepper.solve_dae(y,y_dot);
229 * @endcode
230 *
231 *
232 * <h3> A differential algebraic equation (DAE) example </h3>
233 *
234 * A more interesting example is a situation where the form $F(y', y, t) = 0$
235 * provides something genuinely more flexible than a typical ordinary
236 * differential equation. Specifically, consider the equation
237 * @f{align*}{
238 * u'(t) &= av(t),
239 * \\
240 * 0 &= v(t) - u(t).
241 * @f}
242 * One can combine the two variables into $y(t) = [u(t), v(t)]^T$.
243 * Here, one of the two variables does not have a time derivative. In
244 * applications, this is often the case when one variable evolves in
245 * time (here, $u(t)$) on its own time scale, and the other one finds
246 * its value as a function of the former on a much faster time scale.
247 * In the current context, we could of course easily eliminate $v(t)$
248 * using the second equation, and would then just be left with the
249 * equation
250 * @f[
251 * u'(t) = au(t)
252 * @f]
253 * which has solution $u(t) = u(0)e^{at}$. But this is, in general, not
254 * easily possible if the two variables are related by differential
255 * operators. In fact, this happens quite frequently in application. Take,
256 * for example, the time-dependent Stokes equations:
257 * @f{align*}{
258 * \frac{\partial \mathbf u(\mathbf x,t)}{\partial t}
259 * - \nu \Delta \mathbf u(\mathbf x,t) + \nabla p(\mathbf x,t)
260 * &= \mathbf f(\mathbf x,t),
261 * \\
262 * \nabla \cdot \mathbf u(\mathbf x,t) &= 0.
263 * @f}
264 * Here, the fluid velocity $\mathbf u(\mathbf x,t)$ evolves over time,
265 * and the pressure is always in equilibrium with the flow because the Stokes
266 * equations are derived under the assumption that the speed of sound (at
267 * which pressure perturbations propagate) is much larger than the fluid
268 * velocity. As a consequence, there is no time derivative on the pressure
269 * available in the equation, but unlike the simple model problem above, the
270 * pressure can not easily be eliminated from the system. Similar situations
271 * happen in step-21, step-31, step-32, step-43, and others, where a subset of
272 * variables is always in instantaneous equilibrium with another set of
273 * variables that evolves on a slower time scale.
274 *
275 * Another case where we *could* eliminate a variable but do not want to
276 * is where that additional variable is introduced in the first place to work
277 * around some other problem. As an example, consider the time dependent
278 * version of the biharmonic problem we consider in step-47 (as well as some
279 * later ones). The equations we would then be interested in would read
280 * @f{align*}{
281 * \frac{\partial u(\mathbf x,t)}{\partial t} + \Delta^2 u(\mathbf x,t) &=
282 * f(\mathbf x,t).
283 * @f}
284 * As discussed in step-47, the difficulty is the presence of the fourth
285 * derivatives. One way in which one can address this is by introducing
286 * an auxiliary variable $v=\Delta u$ which would render the problem into
287 * the following one that only ever has second derivatives which we know
288 * how to deal with:
289 * @f{align*}{
290 * \frac{\partial u(\mathbf x,t)}{\partial t} + \Delta v(\mathbf x,t) &=
291 * f(\mathbf x,t),
292 * \\
293 * v(\mathbf x,t)-\Delta u(\mathbf x,t) &= 0.
294 * @f}
295 * Here, the introduction of the additional variable was voluntary, and
296 * could be undone, but we don't want that of course. Rather, we end
297 * up with a differential-algebraic equation because the equations do
298 * not have a time derivative for $v$.
299 *
300 * Rather than show how to solve the trivial (linear) case above, let us
301 * instead consider the situation where we introduce another variable $v$ that
302 * is related to $u$ by the nonlinear relationship $v=u^p$, $p\ge 1$:
303 * @f{align*}{
304 * u'(t) &= a v(t)^{1/p},
305 * \\
306 * 0 &= v(t) - u(t)^p.
307 * @f}
308 * We will impose initial conditions as
309 * @f{align*}{
310 * u(0) &= 1 \\
311 * v(0) &= 1.
312 * @f}
313 * The problem continues to have the solution $u(t)=e^{at}$ with the
314 * auxiliary variable satisfying $v(t)=[e^{at}]^p$. One would implement
315 * all of this using the following little program where you have to recall
316 * that
317 * @f[
318 * F = \begin{pmatrix}u' -a v^{1/p} \\ -u^p + v \end{pmatrix}
319 * @f]
320 * and that the Jacobian we need to provide is
321 * @f[
322 * J(\alpha) =
323 * = \dfrac{\partial F}{\partial y} +
324 * \alpha \dfrac{\partial F}{\partial \dot y}
325 * = \begin{pmatrix} \alpha && -av^{1/p-1}/p \\ -pu^{p-1} & 1 \end{pmatrix}
326 * @f]
327 *
328 * All of this can be implemented using the following code:
329 * @code
330 * const double a = 1.0;
331 * const double p = 1.5;
332 *
333 * using VectorType = Vector<double>;
334 *
335 * VectorType y(2);
336 * VectorType y_dot(2);
337 * FullMatrix<double> J(2, 2);
338 * FullMatrix<double> A(2, 2);
339 * FullMatrix<double> Jinv(2, 2);
340 *
341 * SUNDIALS::IDA<VectorVector> time_stepper;
342 *
343 * time_stepper.reinit_vector = [&](VectorType &v) {
344 * v.reinit(2);
345 * };
346 *
347 * time_stepper.residual = [&](const double t,
348 * const VectorType &y,
349 * const VectorType &y_dot,
350 * VectorType &res) {
351 * // F(Y', Y, t) = [x' -a y^{1/p} ; -x^p + y]
352 * res = 0;
353 * res[0] = y_dot[0] - a * std::pow(y[1], 1./p);
354 * res[1] = -std::pow(y[0], p) + y[1];
355 * };
356 *
357 * time_stepper.setup_jacobian = [&](const double,
358 * const VectorType &y,
359 * const VectorType &,
360 * const double alpha) {
361 * // J = [alpha -ay^{1/p-1}/p ; -px^{p-1} 1]
362 * J(0, 0) = alpha;
363 * J(0, 1) = -a*std::pow(y[1], 1./p-1)/p;
364 * J(1, 0) = -p*std::pow(y[0], p-1);
365 * J(1, 1) = 1;
366 *
367 * Jinv.invert(J);
368 * };
369 *
370 * time_stepper.solve_with_jacobian =
371 * [&](const VectorType &src, VectorType &dst, const double) {
372 * Jinv.vmult(dst, src);
373 * };
374 *
375 * // Provide initial values:
376 * y[0] = y[1] = 1;
377 * // Also provide initial derivatives. Note that
378 * // v'(0) = d/dt[u^p](0) = p[u'(0)]^{p-1} = p a^{p-1}
379 * y_dot[0] = a;
380 * y_dot[1] = p*std::pow(a, p-1);
381 * time_stepper.solve_dae(y, y_dot);
382 * @endcode
383 * Note that in this code, we not only provide initial conditions for
384 * $u$ and $v$, but also for $u'$ and $v'$. We can do this here because
385 * we know what the exact solution is.
386 *
387 *
388 * <h3> DAEs with missing initial conditions </h3>
389 *
390 * Whereas in the previous section, we were able to provide not only
391 * initial values in the form of a vector for $y(0)$, but also for
392 * $y'(0)$, this is not a common situation. For example, for the Stokes
393 * equations mentioned above,
394 * @f{align*}{
395 * \frac{\partial \mathbf u(\mathbf x,t)}{\partial t}
396 * - \nu \Delta \mathbf u(\mathbf x,t) + \nabla p(\mathbf x,t)
397 * &= \mathbf f(\mathbf x,t),
398 * \\
399 * \nabla \cdot \mathbf u(\mathbf x,t) &= 0,
400 * @f}
401 * one generally might have an initial velocity field for
402 * $\mathbf u(\mathbf x,0)$, but typically one does not have an initial
403 * pressure field $p(\mathbf x,0)$ nor either of these variables' time
404 * derivatives at $t=0$.
405 *
406 * Fortunately, they can typically be computed via the relationship
407 * $F(t,y,\dot y) = 0$. To illustrate how this can is done, let us
408 * re-use the nonlinear example from the previous section:
409 * @f{align*}{
410 * u'(t) &= a v(t)^{1/p},
411 * \\
412 * 0 &= v(t) - u(t)^p.
413 * @f}
414 * If we now impose initial conditions for both variables, for
415 * example
416 * @f{align*}{
417 * u(0) &= 1 \\
418 * v(0) &= 1,
419 * @f}
420 * then the only change necessary is to create the time stepper via
421 * @code
422 * SUNDIALS::IDA<VectorType>::AdditionalData data;
423 * data.ic_type = SUNDIALS::IDA<VectorType>::AdditionalData::use_y_diff;
424 * SUNDIALS::IDA<Vector<double>> time_stepper(data);
425 * @endcode
426 * and then we can run the program with the following at the end:
427 * @code
428 * // Provide correct initial conditions y(0), but incorrect initial
429 * // derivatives y'(0):
430 * y[0] = y[1] = 1; // correct
431 * y_dot[0] = 0; // wrong
432 * y_dot[1] = 0; // wrong
433 * time_stepper.solve_dae(y, y_dot);
434 * @endcode
435 * Here, IDA first compute $\dot y(0)$ before starting the time stepping
436 * process.
437 *
438 * In many applications, however, one does not even have a complete set of
439 * initial conditions -- e.g., in the Stokes equations above, one generally
440 * only has initial values for the velocity, but not the pressure. IDA can
441 * also compute these, but for that it needs to know which components of the
442 * solution vector have differential equations attached to them -- i.e., for
443 * which components a time derivative appears in $F(t,y,\dot y)$. This is
444 * not difficult to do -- we only have to add the following block where a
445 * lambda function returns an IndexSet that describes which variables
446 * are "differential" (included in the index set) and which are not (not
447 * included in the index set):
448 * @code
449 * time_stepper.differential_components = []() {
450 * IndexSet x(2);
451 * x.add_index(0);
452 * return x;
453 * };
454 *
455 * y[0] = 1; // correct
456 * y[1] = 42; // wrong
457 * y_dot[0] = 0; // wrong
458 * y_dot[1] = 0; // wrong
459 * time_stepper.solve_dae(y, y_dot);
460 * @endcode
461 * With these modifications, IDA correctly computes the solutions $u(t)$
462 * and $v(t)$.
463 *
464 * A word of caution, however: All of this solving for components of
465 * $y(0)$ and $y'(t)$ costs time and accuracy. If you *can* provide initial
466 * conditions, you should; if you can't, they have to be numerically
467 * approximated and will be close but not exact. In the examples above,
468 * if all initial conditions $y(0),\dot y(0)$ are provided, IDA computes
469 * the solution $y(10)=e^{10}\approx 22,000$ to an absolute accuracy of
470 * around $3\cdot 10^{-5}$ (i.e., to a relative tolerance of better than
471 * $10^{-8}$). If you only provide $y(0)$ correctly, the absolute error
472 * is about twice as large, around $6\cdot 10^{-5}$. If one also omits
473 * providing the initial value for the second component of $y(0)$ (the
474 * non-differential component $v(0)$), the error goes up to $5\cdot 10^{-4}$.
475 * That's not bad, but the trend is clear. In practice, one can control
476 * the accuracy of the required solves for initial conditions by
477 * setting the appropriate flags in the AdditionalData object passed to
478 * the constructor.
479 */
480 template <typename VectorType = Vector<double>>
481 class IDA
482 {
483 public:
484 /**
485 * Additional parameters that can be passed to the IDA class.
486 */
487 class AdditionalData
488 {
489 public:
490 /**
491 * IDA is a Differential Algebraic solver. As such, it requires initial
492 * conditions also for the first order derivatives. If you do not provide
493 * consistent initial conditions, (i.e., conditions for which $F(\dot
494 * y(0), y(0), 0) = 0)$, you can ask SUNDIALS to compute initial
495 * conditions for you by specifying InitialConditionCorrection for the
496 * initial conditions both at the `initial_time` (`ic_type`) and after a
497 * reset has occurred (`reset_type`).
498 */
499 enum InitialConditionCorrection
500 {
501 /**
502 * Do not try to make initial conditions consistent.
503 */
504 none = 0,
505
506 /**
507 * Compute the algebraic components of $y$ and differential
508 * components of $\dot y$, given the differential components of $y$.
509 * This option requires that the user specifies differential and
510 * algebraic components in the function
511 * IDA::differential_components().
512 */
513 use_y_diff = 1,
514
515 /**
516 * Compute all components of $y$, given $\dot y$.
517 */
518 use_y_dot = 2
519 };
520
521 /**
522 * Initialization parameters for IDA.
523 *
524 * Global parameters:
525 *
526 * @param initial_time Initial time
527 * @param final_time Final time
528 * @param initial_step_size Initial step size
529 * @param output_period Time interval between each output
530 *
531 * Running parameters:
532 *
533 * @param minimum_step_size Minimum step size
534 * @param maximum_order Maximum BDF order
535 * @param maximum_non_linear_iterations Maximum number of nonlinear
536 * iterations
537 * @param ls_norm_factor Converting factor from the integrator tolerance
538 * to the linear solver tolerance
539 * iterations
540 *
541 * Error parameters:
542 *
543 * @param absolute_tolerance Absolute error tolerance
544 * @param relative_tolerance Relative error tolerance
545 * @param ignore_algebraic_terms_for_errors Ignore algebraic terms for
546 * error computations
547 *
548 * Initial condition correction parameters:
549 *
550 * @param ic_type Initial condition correction type
551 * @param reset_type Initial condition correction type after restart
552 * @param maximum_non_linear_iterations_ic Initial condition Newton max
553 * iterations
554 */
555 AdditionalData( // Initial parameters
556 const double initial_time = 0.0,
557 const double final_time = 1.0,
558 const double initial_step_size = 1e-2,
559 const double output_period = 1e-1,
560 // Running parameters
561 const double minimum_step_size = 1e-6,
562 const unsigned int maximum_order = 5,
563 const unsigned int maximum_non_linear_iterations = 10,
564 const double ls_norm_factor = 0,
565 // Error parameters
566 const double absolute_tolerance = 1e-6,
567 const double relative_tolerance = 1e-5,
568 const bool ignore_algebraic_terms_for_errors = true,
569 // Initial conditions parameters
570 const InitialConditionCorrection &ic_type = use_y_diff,
571 const InitialConditionCorrection &reset_type = use_y_diff,
572 const unsigned int maximum_non_linear_iterations_ic = 5)
573 : initial_time(initial_time)
574 , final_time(final_time)
575 , initial_step_size(initial_step_size)
576 , minimum_step_size(minimum_step_size)
577 , absolute_tolerance(absolute_tolerance)
578 , relative_tolerance(relative_tolerance)
579 , maximum_order(maximum_order)
580 , output_period(output_period)
581 , ignore_algebraic_terms_for_errors(ignore_algebraic_terms_for_errors)
582 , ic_type(ic_type)
583 , reset_type(reset_type)
584 , maximum_non_linear_iterations_ic(maximum_non_linear_iterations_ic)
585 , maximum_non_linear_iterations(maximum_non_linear_iterations)
586 , ls_norm_factor(ls_norm_factor)
587 {}
588
589 /**
590 * Add all AdditionalData() parameters to the given ParameterHandler
591 * object. When the parameters are parsed from a file, the internal
592 * parameters are automatically updated.
593 *
594 * The following parameters are declared:
595 *
596 * @code
597 * set Final time = 1.000000
598 * set Initial time = 0.000000
599 * set Time interval between each output = 0.2
600 * subsection Error control
601 * set Absolute error tolerance = 0.000001
602 * set Ignore algebraic terms for error computations = true
603 * set Relative error tolerance = 0.00001
604 * set Use local tolerances = false
605 * end
606 * subsection Initial condition correction parameters
607 * set Correction type at initial time = none
608 * set Correction type after restart = none
609 * set Maximum number of nonlinear iterations = 5
610 * end
611 * subsection Running parameters
612 * set Initial step size = 0.1
613 * set Maximum number of nonlinear iterations = 10
614 * set Maximum order of BDF = 5
615 * set Minimum step size = 0.000001
616 * end
617 * @endcode
618 *
619 * These are one-to-one with the options you can pass at construction
620 * time.
621 *
622 * The options you pass at construction time are set as default values in
623 * the ParameterHandler object `prm`. You can later modify them by parsing
624 * a parameter file using `prm`. The values of the parameter will be
625 * updated whenever the content of `prm` is updated.
626 *
627 * Make sure that this class lives longer than `prm`. Undefined behavior
628 * will occur if you destroy this class, and then parse a parameter file
629 * using `prm`.
630 */
631 void
632 add_parameters(ParameterHandler &prm)
633 {
634 prm.add_parameter("Initial time", initial_time);
635 prm.add_parameter("Final time", final_time);
636 prm.add_parameter("Time interval between each output", output_period);
637
638 prm.enter_subsection("Running parameters");
639 prm.add_parameter("Initial step size", initial_step_size);
640 prm.add_parameter("Minimum step size", minimum_step_size);
641 prm.add_parameter("Maximum order of BDF", maximum_order);
642 prm.add_parameter("Maximum number of nonlinear iterations",
643 maximum_non_linear_iterations);
644 prm.leave_subsection();
645
646 prm.enter_subsection("Error control");
647 prm.add_parameter("Absolute error tolerance", absolute_tolerance);
648 prm.add_parameter("Relative error tolerance", relative_tolerance);
649 prm.add_parameter(
650 "Ignore algebraic terms for error computations",
651 ignore_algebraic_terms_for_errors,
652 "Indicate whether or not to suppress algebraic variables "
653 "in the local error test.");
654 prm.leave_subsection();
655
656 prm.enter_subsection("Initial condition correction parameters");
657 static std::string ic_type_str = "use_y_diff";
658 prm.add_parameter(
659 "Correction type at initial time",
660 ic_type_str,
661 "This is one of the following three options for the "
662 "initial condition calculation. \n"
663 " none: do not try to make initial conditions consistent. \n"
664 " use_y_diff: compute the algebraic components of y and differential\n"
665 " components of y_dot, given the differential components of y. \n"
666 " This option requires that the user specifies differential and \n"
667 " algebraic components in the function differential_components().\n"
668 " use_y_dot: compute all components of y, given y_dot.",
669 Patterns::Selection("none|use_y_diff|use_y_dot"));
670 prm.add_action("Correction type at initial time",
671 [&](const std::string &value) {
672 if (value == "use_y_diff")
673 ic_type = use_y_diff;
674 else if (value == "use_y_dot")
675 ic_type = use_y_dot;
676 else if (value == "none")
677 ic_type = none;
678 else
679 AssertThrow(false, ExcInternalError());
680 });
681
682 static std::string reset_type_str = "use_y_diff";
683 prm.add_parameter(
684 "Correction type after restart",
685 reset_type_str,
686 "This is one of the following three options for the "
687 "initial condition calculation. \n"
688 " none: do not try to make initial conditions consistent. \n"
689 " use_y_diff: compute the algebraic components of y and differential\n"
690 " components of y_dot, given the differential components of y. \n"
691 " This option requires that the user specifies differential and \n"
692 " algebraic components in the function differential_components().\n"
693 " use_y_dot: compute all components of y, given y_dot.",
694 Patterns::Selection("none|use_y_diff|use_y_dot"));
695 prm.add_action("Correction type after restart",
696 [&](const std::string &value) {
697 if (value == "use_y_diff")
698 reset_type = use_y_diff;
699 else if (value == "use_y_dot")
700 reset_type = use_y_dot;
701 else if (value == "none")
702 reset_type = none;
703 else
704 AssertThrow(false, ExcInternalError());
705 });
706 prm.add_parameter("Maximum number of nonlinear iterations",
707 maximum_non_linear_iterations_ic);
708 prm.add_parameter(
709 "Factor to use when converting from the integrator tolerance to the linear solver tolerance",
710 ls_norm_factor);
711 prm.leave_subsection();
712 }
713
714 /**
715 * Initial time for the DAE.
716 */
717 double initial_time;
718
719 /**
720 * Final time.
721 */
722 double final_time;
723
724 /**
725 * Initial step size.
726 */
727 double initial_step_size;
728
729 /**
730 * Minimum step size.
731 */
732 double minimum_step_size;
733
734 /**
735 * Absolute error tolerance for adaptive time stepping.
736 */
737 double absolute_tolerance;
738
739 /**
740 * Relative error tolerance for adaptive time stepping.
741 */
742 double relative_tolerance;
743
744 /**
745 * Maximum order of BDF.
746 */
747 unsigned int maximum_order;
748
749 /**
750 * Time period between each output.
751 */
752 double output_period;
753
754 /**
755 * Ignore algebraic terms for errors.
756 */
757 bool ignore_algebraic_terms_for_errors;
758
759 /**
760 * Type of correction for initial conditions.
761 *
762 * If you do not provide consistent initial conditions, (i.e., conditions
763 * for which $F(y_dot(0), y(0), 0) = 0$), you can ask SUNDIALS to compute
764 * initial conditions for you by using the `ic_type` parameter at
765 * construction time.
766 *
767 * Notice that you could in principle use this capabilities to solve for
768 * steady state problems by setting y_dot to zero, and asking to compute
769 * $y(0)$ that satisfies $F(0, y(0), 0) = 0$, however the nonlinear solver
770 * used inside IDA may not be robust enough for complex problems with
771 * several millions unknowns.
772 */
773 InitialConditionCorrection ic_type;
774
775 /**
776 * Type of correction for initial conditions to be used after a solver
777 * restart.
778 *
779 * If you do not have consistent initial conditions after a restart,
780 * (i.e., conditions for which F(y_dot(t_restart), y(t_restart),
781 * t_restart) = 0), you can ask SUNDIALS to compute the new initial
782 * conditions for you by using the `reset_type` parameter at construction
783 * time.
784 */
785 InitialConditionCorrection reset_type;
786
787 /**
788 * Maximum number of iterations for Newton method in IC calculation.
789 */
790 unsigned maximum_non_linear_iterations_ic;
791
792 /**
793 * Maximum number of iterations for Newton method during time advancement.
794 */
795 unsigned int maximum_non_linear_iterations;
796
797 /**
798 * Factor to use when converting from the integrator tolerance to the
799 * linear solver tolerance
800 */
801 double ls_norm_factor;
802 };
803
804 /**
805 * Constructor. It is possible to fine tune the SUNDIALS IDA solver by
806 * passing an AdditionalData() object that sets all of the solver
807 * parameters.
808 *
809 * IDA is a Differential Algebraic solver. As such, it requires initial
810 * conditions also for the first order derivatives. If you do not provide
811 * consistent initial conditions, (i.e., conditions for which F(y_dot(0),
812 * y(0), 0) = 0), you can ask SUNDIALS to compute initial conditions for you
813 * by using the `ic_type` parameter at construction time.
814 *
815 * You have three options
816 * - none: do not try to make initial conditions consistent.
817 * - use_y_diff: compute the algebraic components of y and differential
818 * components of y_dot, given the differential components of y.
819 * This option requires that the user specifies differential and
820 * algebraic components in the function differential_components().
821 * - use_y_dot: compute all components of y, given y_dot.
822 *
823 * By default, this class assumes that all components are differential, and
824 * that you want to solve a standard ode. In this case, the initial
825 * component type is set to `use_y_diff`, so that the `y_dot` at time
826 * t=`initial_time` is computed by solving the nonlinear problem $F(y_dot,
827 * y(t0), t0) = 0$ in the variable `y_dot`.
828 *
829 * Notice that a Newton solver is used for this computation. The Newton
830 * solver parameters can be tweaked by acting on `ic_alpha` and
831 * `ic_max_iter`.
832 *
833 * If you reset the solver at some point, you may want to select a different
834 * computation for the initial conditions after reset. Say, for example,
835 * that you have refined a grid, and after transferring the solution to the
836 * new grid, the initial conditions are no longer consistent. Then you can
837 * choose how these are made consistent, using the same three options that
838 * you used for the initial conditions in `reset_type`.
839 *
840 * @param data IDA configuration data
841 *
842 * @note With SUNDIALS 6 and later this constructor sets up logging
843 * objects to only work on the present processor (i.e., results are only
844 * communicated over MPI_COMM_SELF).
845 */
846 IDA(const AdditionalData &data = AdditionalData());
847
848 /**
849 * Constructor.
850 *
851 * @param data IDA configuration data. Same as the other constructor.
852 * @param mpi_comm MPI Communicator over which logging operations are
853 * computed. Only used in SUNDIALS 6 and newer.
854 */
855 IDA(const AdditionalData &data, const MPI_Comm mpi_comm);
856
857 /**
858 * Destructor.
859 */
860 ~IDA();
861
862 /**
863 * Integrate differential-algebraic equations. This function returns the
864 * final number of computed steps.
865 */
866 unsigned int
867 solve_dae(VectorType &solution, VectorType &solution_dot);
868
869 /**
870 * Clear internal memory and start with clean objects. This function is
871 * called when the simulation start and when the user returns true to a
872 * call to solver_should_restart().
873 *
874 * By default solver_should_restart() returns false. If the user needs to
875 * implement, for example, local adaptivity in space, he or she may assign
876 * a different function to solver_should_restart() that performs all mesh
877 * changes, transfers the solution and the solution dot to the new mesh,
878 * and returns true.
879 *
880 * During reset(), both y and yp are checked for consistency, and according
881 * to what was specified as ic_type (if t==initial_time) or reset_type (if
882 * t>initial_time), yp, y, or both are modified to obtain a consistent set
883 * of initial data.
884 *
885 * @param[in] t The new starting time
886 * @param[in] h The new (tentative) starting time step
887 * @param[in,out] y The new (tentative) initial solution
888 * @param[in,out] yp The new (tentative) initial solution_dot
889 */
890 void
891 reset(const double t, const double h, VectorType &y, VectorType &yp);
892
893 /**
894 * Reinit vector to have the right size, MPI communicator, etc.
895 */
896 std::function<void(VectorType &)> reinit_vector;
897
898 /**
899 * Compute residual. Return $F(t, y, \dot y)$.
900 *
901 * @note This variable represents a
902 * @ref GlossUserProvidedCallBack "user provided callback".
903 * See there for a description of how to deal with errors and other
904 * requirements and conventions. In particular, IDA can deal
905 * with "recoverable" errors in some circumstances, so callbacks
906 * can throw exceptions of type RecoverableUserCallbackError.
907 */
908 std::function<void(const double t,
909 const VectorType &y,
910 const VectorType &y_dot,
911 VectorType &res)>
912 residual;
913
914 /**
915 * Compute Jacobian. This function is called by IDA any time a Jacobian
916 * update is required. The user should compute the Jacobian (or update all
917 * the variables that allow the application of the Jacobian). This function
918 * is called by IDA once, before any call to solve_with_jacobian().
919 *
920 * The Jacobian $J$ should be a (possibly inexact) computation of
921 * \f[
922 * J=\dfrac{\partial G}{\partial y} = \dfrac{\partial F}{\partial y} +
923 * \alpha \dfrac{\partial F}{\partial \dot y}.
924 * \f]
925 *
926 * If the user uses a matrix based computation of the Jacobian, then this
927 * is the right place where an assembly routine should be called to
928 * assemble both a matrix and a preconditioner for the Jacobian system.
929 * Subsequent calls (possibly more than one) to solve_with_jacobian() can
930 * assume that this function has been called at least once.
931 *
932 * Notice that no assumption is made by this interface on what the user
933 * should do in this function. IDA only assumes that after a call to
934 * setup_jacobian() it is possible to call solve_with_jacobian() to obtain a
935 * solution $x$ to the system $J x = b$.
936 *
937 * @note This variable represents a
938 * @ref GlossUserProvidedCallBack "user provided callback".
939 * See there for a description of how to deal with errors and other
940 * requirements and conventions. In particular, IDA can deal
941 * with "recoverable" errors in some circumstances, so callbacks
942 * can throw exceptions of type RecoverableUserCallbackError.
943 */
944 std::function<void(const double t,
945 const VectorType &y,
946 const VectorType &y_dot,
947 const double alpha)>
948 setup_jacobian;
949
950 /**
951 * Solve the Jacobian linear system up to a specified tolerance. This
952 * function will be called by IDA (possibly several times) after
953 * setup_jacobian() has been called at least once. IDA tries to do its best
954 * to call setup_jacobian() the minimum number of times. If convergence can
955 * be achieved without updating the Jacobian, then IDA does not call
956 * setup_jacobian() again. If, on the contrary, internal IDA convergence
957 * tests fail, then IDA calls again setup_jacobian() with updated vectors
958 * and coefficients so that successive calls to
959 * solve_with_jacobian() lead to better convergence in the
960 * Newton process.
961 *
962 * The Jacobian $J$ should be (an approximation of) the system Jacobian
963 * \f[
964 * J=\dfrac{\partial G}{\partial y} = \dfrac{\partial F}{\partial y} +
965 * \alpha \dfrac{\partial F}{\partial \dot y}.
966 * \f]
967 *
968 * Arguments to the function are:
969 *
970 * @param[in] rhs The system right hand side to solve for.
971 * @param[out] dst The solution of $J^{-1} * src$.
972 * @param[in] tolerance The tolerance with which to solve the linear system
973 * of equations.
974 *
975 * A call to this function should store in `dst` the result of $J^{-1}$
976 * applied to `src`, i.e., the solution of the linear system `J*dst = src`.
977 * It is the user's responsibility to set up proper solvers and
978 * preconditioners either inside this function, or already within the
979 * `setup_jacobian()` function. (The latter is, for example, what the
980 * step-77 program does: All expensive operations happen in
981 * `setup_jacobian()`, given that that function is called far less often
982 * than the current one.)
983 *
984 * @note This variable represents a
985 * @ref GlossUserProvidedCallBack "user provided callback".
986 * See there for a description of how to deal with errors and other
987 * requirements and conventions. In particular, IDA can deal
988 * with "recoverable" errors in some circumstances, so callbacks
989 * can throw exceptions of type RecoverableUserCallbackError.
990 */
991 std::function<
992 void(const VectorType &rhs, VectorType &dst, const double tolerance)>
993 solve_with_jacobian;
994
995 /**
996 * Process solution. This function is called by IDA at fixed time steps,
997 * every `output_period` seconds, and it is passed a polynomial
998 * interpolation of the solution and of its time derivative, computed using
999 * the current BDF order and the (internally stored) previously computed
1000 * solution steps.
1001 *
1002 * Notice that it is well possible that internally IDA computes a time step
1003 * which is much larger than the `output_period` step, and therefore calls
1004 * this function consecutively several times by simply performing all
1005 * intermediate interpolations. There is no relationship between how many
1006 * times this function is called and how many time steps have actually been
1007 * computed.
1008 */
1009 std::function<void(const double t,
1010 const VectorType &sol,
1011 const VectorType &sol_dot,
1012 const unsigned int step_number)>
1013 output_step;
1014
1015 /**
1016 * Evaluate whether the solver should be restarted (for example because the
1017 * number of degrees of freedom has changed).
1018 *
1019 * This function is supposed to perform all operations that are necessary in
1020 * `sol` and `sol_dot` to make sure that the resulting vectors are
1021 * consistent, and of the correct final size.
1022 *
1023 * For example, one may decide that a local refinement is necessary at time
1024 * t. This function should then return true, and change the dimension of
1025 * both sol and sol_dot to reflect the new dimension. Since IDA does not
1026 * know about the new dimension, an internal reset is necessary.
1027 *
1028 * The default implementation simply returns `false`, i.e., no restart is
1029 * performed during the evolution.
1030 *
1031 * @note This variable represents a
1032 * @ref GlossUserProvidedCallBack "user provided callback".
1033 * See there for a description of how to deal with errors and other
1034 * requirements and conventions. In particular, IDA can deal
1035 * with "recoverable" errors in some circumstances, so callbacks
1036 * can throw exceptions of type RecoverableUserCallbackError.
1037 */
1038 std::function<bool(const double t, VectorType &sol, VectorType &sol_dot)>
1039 solver_should_restart;
1040
1041 /**
1042 * Return an index set containing the differential components.
1043 * Implementation of this function is optional. The default is to return a
1044 * complete index set. If your equation is also algebraic (i.e., it
1045 * contains algebraic constraints, or Lagrange multipliers), you should
1046 * overwrite this function in order to return only the differential
1047 * components of your system.
1048 *
1049 * When running in parallel, every process will call this function
1050 * independently, and synchronization will happen at the end of the
1051 * initialization setup to communicate what components are local. Make sure
1052 * you only return the locally owned (or locally relevant) components, in
1053 * order to minimize communication between processes.
1054 */
1055 std::function<IndexSet()> differential_components;
1056
1057 /**
1058 * Return a vector whose components are the weights used by IDA to compute
1059 * the vector norm. The implementation of this function is optional. If the
1060 * user does not provide an implementation, the weights are assumed to be
1061 * all ones.
1062 */
1063 std::function<VectorType &()> get_local_tolerances;
1064
1065 /**
1066 * Handle IDA exceptions.
1067 */
1068 DeclException1(ExcIDAError,
1069 int,
1070 << "One of SUNDIALS IDA's internal functions "
1071 << "returned an error code: " << arg1
1072 << ". Please consult SUNDIALS manual.");
1073
1074
1075 private:
1076 /**
1077 * Throw an exception when a function with the given name is not
1078 * implemented.
1079 */
1080 DeclException1(ExcFunctionNotProvided,
1081 std::string,
1082 << "Please provide an implementation for the function \""
1083 << arg1 << "\"");
1084
1085 /**
1086 * This function is executed at construction time to set the
1087 * std::function above to trigger an assert if they are not
1088 * implemented.
1089 */
1090 void
1091 set_functions_to_trigger_an_assert();
1092
1093 /**
1094 * IDA configuration data.
1095 */
1096 const AdditionalData data;
1097
1098 /**
1099 * IDA memory object.
1100 */
1101 void *ida_mem;
1102
1103 # if DEAL_II_SUNDIALS_VERSION_GTE(6, 0, 0)
1104 /**
1105 * A context object associated with the IDA solver.
1106 */
1107 SUNContext ida_ctx;
1108 # endif
1109
1110 /**
1111 * MPI communicator. Only used for SUNDIALS' logging routines - the actual
1112 * solve routines will use the communicator provided by the vector class.
1113 */
1114 MPI_Comm mpi_communicator;
1115
1116 /**
1117 * Memory pool of vectors.
1118 */
1119 GrowingVectorMemory<VectorType> mem;
1120
1121 /**
1122 * A pointer to any exception that may have been thrown in user-defined
1123 * call-backs and that we have to deal after the KINSOL function we call
1124 * has returned.
1125 */
1126 mutable std::exception_ptr pending_exception;
1127
1128 # ifdef DEAL_II_WITH_PETSC
1129 # ifdef PETSC_USE_COMPLEX
1130 static_assert(!std::is_same_v<VectorType, PETScWrappers::MPI::Vector>,
1131 "Sundials does not support complex scalar types, "
1132 "but PETSc is configured to use a complex scalar type!");
1133
1134 static_assert(!std::is_same_v<VectorType, PETScWrappers::MPI::BlockVector>,
1135 "Sundials does not support complex scalar types, "
1136 "but PETSc is configured to use a complex scalar type!");
1137 # endif // PETSC_USE_COMPLEX
1138 # endif // DEAL_II_WITH_PETSC
1139 };
1140 } // namespace SUNDIALS
1141
1142 DEAL_II_NAMESPACE_CLOSE
1143
1144 #else
1145
1146 // Make sure the scripts that create the C++20 module input files have
1147 // something to latch on if the preprocessor #ifdef above would
1148 // otherwise lead to an empty content of the file.
1149 DEAL_II_NAMESPACE_OPEN
1150 DEAL_II_NAMESPACE_CLOSE
1151
1152 #endif // DEAL_II_WITH_SUNDIALS
1153
1154 #endif