 |
deal.II version GIT relicensing-6834-g5b78e6bcdf 2026-10-01 11:20:01+00:00
|
Loading...
Searching...
No Matches
|
deal.II version GIT relicensing-6834-g5b78e6bcdf 2026-10-01 11:20:01+00:00
|
#include <deal.II/sundials/arkode.h>
Interface to SUNDIALS additive Runge-Kutta methods (ARKode).
The class ARKode is a wrapper to SUNDIALS adaptive-step time integration modules for stiff, nonstiff and mixed stiff/nonstiff systems of ordinary differential equations (ODEs). This class provides access to general underlying infrastructure of ARKODE, controls the main time marching loop, output, reinitializaiton, exception handling. The class ARKode does not implement any time integration strategies itself. Instead, it employs one of the available stepper classes, which are basically wrappers around the corresponding ARKODE steppers. Currently, ARKStepper and ERKStepper are available: ARKStepper provides interfaces to ARKODE's additive Runge-Kutta steppers (supporting implicit, explicit, and mixed methods), while ERKStepper wraps the explicit-only ERKStep module for non-stiff problems. LSRKStepper provides access to the LSRKStep STS (Stabilized explicit Runge-Kutta) and SSP (Strong-Stability-Preserving) family of low-storage Runge-Kutta methods. The documentation of the ARKStepper, ERKStepper, and LSRKStepper classes also shows examples of how this class can be used. Users can also provide their own steppers or implement wrappers around, e.g., SPRKStep or MRIStep modules of ARKODE.
The integrator settings are primarily customized by setting up fields of ARKode::AdditionalData passed to the constructors. For most of the cases, it is advised to set at least the end time up to which the time integrator should run and the initial time step size.
The following functions can be provided to tune the behavior of ARKode:
Forward declare ARKode class.
Classes | |
| class | AdditionalData |
| struct | FunctionProxy |
Public Member Functions | |
| ARKode (const AdditionalData &data=AdditionalData()) | |
| ARKode (const AdditionalData &data, const MPI_Comm mpi_comm) | |
| ARKode (ARKodeStepper< VectorType > &stepper, const AdditionalData &data=AdditionalData()) | |
| ARKode (ARKodeStepper< VectorType > &stepper, const AdditionalData &data, const MPI_Comm mpi_comm) | |
| ~ARKode () | |
| unsigned int | solve_ode (VectorType &solution) |
| unsigned int | solve_ode_incrementally (VectorType &solution, const double intermediate_time, const bool reset_solver=false) |
| void | reset (const double t, const double h, const VectorType &y) |
| void * | get_arkode_memory () const |
Public Attributes | |
| FunctionProxy< void(const double t, const VectorType &y, VectorType &explicit_f)> | explicit_function |
| FunctionProxy< void(const double t, const VectorType &y, VectorType &res)> | implicit_function |
| FunctionProxy< void(const double t, const VectorType &v, VectorType &Mv)> | mass_times_vector |
| FunctionProxy< void(const double t)> | mass_times_setup |
| FunctionProxy< void(const VectorType &v, VectorType &Jv, const double t, const VectorType &y, const VectorType &fy)> | jacobian_times_vector |
| FunctionProxy< void(const double t, const VectorType &y, const VectorType &fy)> | jacobian_times_setup |
| FunctionProxy< void(SundialsOperator< VectorType > &op, SundialsPreconditioner< VectorType > &prec, VectorType &x, const VectorType &b, double tol)> | solve_linearized_system |
| FunctionProxy< void(SundialsOperator< VectorType > &op, SundialsPreconditioner< VectorType > &prec, VectorType &x, const VectorType &b, double tol)> | solve_mass |
| FunctionProxy< void(const double t, const VectorType &y, const VectorType &fy, const VectorType &r, VectorType &z, const double gamma, const double tol, const int lr)> | jacobian_preconditioner_solve |
| FunctionProxy< void(const double t, const VectorType &y, const VectorType &fy, const int jok, int &jcur, const double gamma)> | jacobian_preconditioner_setup |
| FunctionProxy< void(const double t, const VectorType &r, VectorType &z, const double tol, const int lr)> | mass_preconditioner_solve |
| FunctionProxy< void(const double t)> | mass_preconditioner_setup |
| std::function< void(const double t, const VectorType &sol, const unsigned int step_number)> | output_step |
| std::function< bool(const double t, VectorType &sol)> | solver_should_restart |
| std::function< VectorType &()> | get_local_tolerances |
| std::function< void(void *arkode_mem)> | custom_setup |
Private Member Functions | |
| unsigned int | do_evolve_time (VectorType &solution, ::DiscreteTime &time, const bool do_reset) |
| void | set_functions_to_trigger_an_assert () |
| void | initialize_context () |
Static Private Member Functions | |
| static ::ExceptionBase & | ExcFunctionNotProvided (std::string arg1) |
Private Attributes | |
| AdditionalData | data |
| std::unique_ptr< ARKStepper< VectorType > > | ark_stepper_storage {nullptr} |
| ARKodeStepper< VectorType > & | stepper |
| SUNContext | arkode_ctx |
| MPI_Comm | mpi_communicator |
| double | last_end_time |
| std::exception_ptr | pending_exception |
| SUNDIALS::ARKode< VectorType >::ARKode | ( | const AdditionalData & | data = AdditionalData() | ) |
Constructor, with class parameters set by the AdditionalData object.
| data | ARKode configuration data |
| SUNDIALS::ARKode< VectorType >::ARKode | ( | const AdditionalData & | data, |
| const MPI_Comm | mpi_comm | ||
| ) |
| SUNDIALS::ARKode< VectorType >::ARKode | ( | ARKodeStepper< VectorType > & | stepper, |
| const AdditionalData & | data = AdditionalData() |
||
| ) |
Constructor receiving the stepper and optionally the additional data.
| stepper | ARKodeStepper object |
| data | ARKode configuration data |
| SUNDIALS::ARKode< VectorType >::ARKode | ( | ARKodeStepper< VectorType > & | stepper, |
| const AdditionalData & | data, | ||
| const MPI_Comm | mpi_comm | ||
| ) |
Constructor receiving the stepper, additional data, and MPI communicator.
| stepper | ARKodeStepper object |
| data | ARKode configuration data |
| mpi_comm | MPI Communicator over which logging operations are computed. Only used in SUNDIALS 6 and newer. |
| SUNDIALS::ARKode< VectorType >::~ARKode | ( | ) |
Destructor.
| unsigned int SUNDIALS::ARKode< VectorType >::solve_ode | ( | VectorType & | solution | ) |
Integrate the initial value problem. This function returns the final number of computed steps.
| solution | On input, this vector contains the initial condition. On output, it contains the solution at the final time. |
| unsigned int SUNDIALS::ARKode< VectorType >::solve_ode_incrementally | ( | VectorType & | solution, |
| const double | intermediate_time, | ||
| const bool | reset_solver = false |
||
| ) |
Integrate the initial value problem. Compared to the function above, this function allows to specify an intermediate_time for the next solution. Repeated calls of this function must use monotonously increasing values for intermediate_time. The last solution state is saved internally along with the intermediate_time and will be reused as initial condition for the next call.
Users may find this function useful when integrating ARKode into an outer time loop of their own, especially when output_step() is too restrictive.
intermediate_time may be larger than AdditionalData::final_time, which is ignored by this function.| solution | The final solution. If the solver restarts, either because it is the first ever solve or the flag reset_solver is set, the vector is also used as initial condition. |
| intermediate_time | The time for the incremental solution step. Must be greater than the last time that was used in a previous call to this function. |
| reset_solver | Optional flag to recreate all internal objects which may be desirable for spatial adaptivity methods. If set to true, reset() is called before solving the ODE, which sets solution as initial condition. This will not reset the stored time from previous calls to this function. |
| void SUNDIALS::ARKode< VectorType >::reset | ( | const double | t, |
| const double | h, | ||
| const VectorType & | y | ||
| ) |
Clear internal memory and start with clean objects. This function is called when the simulation starts and when the user returns true to a call to solver_should_restart().
By default solver_should_restart() returns false. If the user needs to implement, for example, local adaptivity in space, he or she may assign a different function to solver_should_restart() that performs all mesh changes, transfers the solution to the new mesh, and returns true.
| t | The new starting time |
| h | The new starting time step |
| y | The new initial solution |
| void * SUNDIALS::ARKode< VectorType >::get_arkode_memory | ( | ) | const |
Provides user access to the internally used ARKODE memory.
This functionality is intended for users who wish to query additional information directly from the ARKODE integrator, refer to the ARKODE manual for the various ARKStepGet... functions. The ARKStepSet... functions should not be called since this might lead to conflicts with various settings that are performed by this ARKode object.
|
private |
Internal routine to call ARKode repeatedly.
|
private |
This function is executed at construction time to set the std::function above to trigger an assert if they are not implemented.
|
private |
This function is executed at construction time to initialize the SUNContext object.
| FunctionProxy< void(const double t, const VectorType &y, VectorType &explicit_f)> SUNDIALS::ARKode< VectorType >::explicit_function |
A function object that users may supply and that is intended to compute the explicit part of the IVP right hand side. Sets \(explicit_f = f_E(t, y)\).
ARKStepper::explicit_function instead. | FunctionProxy<void(const double t, const VectorType &y, VectorType &res)> SUNDIALS::ARKode< VectorType >::implicit_function |
A function object that users may supply and that is intended to compute the implicit part of the IVP right hand side. Sets \(implicit_f = f_I(t, y)\).
ARKStepper::implicit_function instead. | FunctionProxy<void(const double t, const VectorType &v, VectorType &Mv)> SUNDIALS::ARKode< VectorType >::mass_times_vector |
A function object that users may supply and that is intended to compute the product of the mass matrix with a given vector v. This function will be called by ARKode (possibly several times) after mass_times_setup() has been called at least once. ARKode tries to do its best to call mass_times_setup() the minimum amount of times.
ARKStepper::mass_times_vector instead. | FunctionProxy<void(const double t)> SUNDIALS::ARKode< VectorType >::mass_times_setup |
A function object that users may supply and that is intended to set up the mass matrix. This function is called by ARKode any time a mass matrix update is required. The user should compute the mass matrix (or update all the variables that allow the application of the mass matrix). This function is guaranteed to be called by ARKode at least once, before any call to mass_times_vector().
ARKStepper::mass_times_vector_setup instead. | FunctionProxy<void(const VectorType &v, VectorType &Jv, const double t, const VectorType &y, const VectorType &fy)> SUNDIALS::ARKode< VectorType >::jacobian_times_vector |
A function object that users may supply and that is intended to compute the product of the Jacobian matrix with a given vector v. The Jacobian here refers to \(J=\frac{\partial f_I}{\partial y}\), i.e., the Jacobian of the user-specified implicit_function.
ARKStepper::jacobian_times_vector instead. | FunctionProxy< void(const double t, const VectorType &y, const VectorType &fy)> SUNDIALS::ARKode< VectorType >::jacobian_times_setup |
A function object that users may supply and that is intended to set up all data necessary for the application of jacobian_times_vector().
ARKStepper::jacobian_times_vector_setup instead. | FunctionProxy<void(SundialsOperator<VectorType> &op, SundialsPreconditioner<VectorType> &prec, VectorType &x, const VectorType &b, double tol)> SUNDIALS::ARKode< VectorType >::solve_linearized_system |
A LinearSolveFunction object that users may supply and that is intended to solve the linearized system \(Ax=b\), where \(A = M-\gamma J\) is the Jacobian of the nonlinear residual.
ARKStepper::solve_linearized_system instead. | FunctionProxy<void(SundialsOperator<VectorType> &op, SundialsPreconditioner<VectorType> &prec, VectorType &x, const VectorType &b, double tol)> SUNDIALS::ARKode< VectorType >::solve_mass |
A LinearSolveFunction object that users may supply and that is intended to solve the mass system \(Mx=b\).
ARKStepper::solve_mass instead. | FunctionProxy<void(const double t, const VectorType &y, const VectorType &fy, const VectorType &r, VectorType &z, const double gamma, const double tol, const int lr)> SUNDIALS::ARKode< VectorType >::jacobian_preconditioner_solve |
A function object that users may supply to either pass a preconditioner to a SUNDIALS built-in solver or to apply a custom preconditioner within the user's own linear solve specified in solve_linearized_system().
ARKStepper::jacobian_preconditioner_solve instead. | FunctionProxy<void(const double t, const VectorType &y, const VectorType &fy, const int jok, int &jcur, const double gamma)> SUNDIALS::ARKode< VectorType >::jacobian_preconditioner_setup |
A function object that users may supply to set up a preconditioner specified in jacobian_preconditioner_solve().
ARKStepper::jacobian_preconditioner_setup instead. | FunctionProxy<void(const double t, const VectorType &r, VectorType &z, const double tol, const int lr)> SUNDIALS::ARKode< VectorType >::mass_preconditioner_solve |
A function object that users may supply to either pass a preconditioner to a SUNDIALS built-in solver or to apply a custom preconditioner within the user's own linear solve specified in solve_mass().
ARKStepper::mass_preconditioner_solve instead. | FunctionProxy<void(const double t)> SUNDIALS::ARKode< VectorType >::mass_preconditioner_setup |
A function object that users may supply to set up a preconditioner specified in mass_preconditioner_setup().
ARKStepper::mass_preconditioner_solve instead. | std::function<void(const double t, const VectorType &sol, const unsigned int step_number)> SUNDIALS::ARKode< VectorType >::output_step |
A function object that users may supply and that is intended to postprocess the solution. This function is called by ARKode at fixed time increments (every output_period time units), and it is passed a polynomial interpolation of the solution, computed using the current ARK order and the (internally stored) previously computed solution steps.
output_period step, and therefore calls this function consecutively several times by simply performing all intermediate interpolations. There is no relationship between how many times this function is called and how many time steps have actually been computed. | std::function<bool(const double t, VectorType &sol)> SUNDIALS::ARKode< VectorType >::solver_should_restart |
A function object that users may supply and that is intended to evaluate whether the solver should be restarted (for example because the number of degrees of freedom has changed).
This function is supposed to perform all operations that are necessary in sol to make sure that the resulting vectors are consistent, and of the correct final size.
For example, one may decide that a local refinement is necessary at time t. This function should then return true, and change the dimension of sol to reflect the new dimension. Since ARKode does not know about the new dimension, an internal reset is necessary.
The default implementation simply returns false, i.e., no restart is performed during the evolution.
| std::function<VectorType &()> SUNDIALS::ARKode< VectorType >::get_local_tolerances |
| std::function<void(void *arkode_mem)> SUNDIALS::ARKode< VectorType >::custom_setup |
A function object that users may supply and which is intended to perform custom settings on the supplied arkode_mem object. Refer to the SUNDIALS documentation for valid options.
For instance, the following code sets Lagrange interpolants to be used for dense output (interpolation of solution output values) and implicit method predictors:
| arkode_mem | pointer to the ARKODE memory block which can be used for custom calls to ARKodeSet... methods. |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
The final time in the last call to solve_ode().
|
mutableprivate |
1.9.8