| 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 |