#include <deal.II/sundials/arkode_stepper.h>

Detailed Description

template<typename VectorType = Vector<double>>
class SUNDIALS::LSRKStepperSTS< VectorType >

Wrapper for the LSRKStep (Low-Storage Runge-Kutta) STS (Super Time-Stepping) family.

STS methods are designed for mildly stiff problems whose Jacobian eigenvalues lie on or near the negative real axis, such as the semidiscretization of parabolic PDEs. The stability region grows as \(O(s^2)\) with the number of stages \(s\), allowing much larger time steps than standard explicit Runge-Kutta methods for the same problem, alleviating to a degree the usual issue that one should not solve parabolic problems with explicit methods (see the discussion in step-26 for example).

LSRKStep also provides the SSP (Strong Stability Preserving) family of the Low-Storage Runge-Kutta methods, which are designed for hyperbolic problems such as advection-dominated fluid flow. These methods are available through LSRKStepperSSP.

Available methods (passed as method_name):

ARKODE_LSRK_RKC_2: Runge-Kutta-Chebyshev of order 2 (default).
ARKODE_LSRK_RKL_2: Runge-Kutta-Legendre of order 2.

Because the number of stages is chosen adaptively based on the spectral radius of the Jacobian, STS methods need an estimate of the dominant (largest-magnitude) eigenvalue of the Jacobian. This estimate can be provided in one of two ways:

By supplying dominant_eigenvalue_function(), in which case SUNDIALS calls back into the user code to obtain the estimate.
By leaving dominant_eigenvalue_function() unset. In that case a SUNDIALS built-in power-iteration dominant-eigenvalue estimator (SUNDomEigEstimator) is created and attached automatically. The estimator obtains the dominant eigenvalue internally from explicit_function() and requires no further input. This default is only available when deal.II is compiled against SUNDIALS 7.5.0 or newer; with older versions dominant_eigenvalue_function() must be provided.

The user has to provide the implementation of the following std::function:

explicit_function()

Optionally, the user may also provide:

dominant_eigenvalue_function()

Any other custom settings of the LSRKStep object can be specified in

custom_setup()

Note: This class is only available when deal.II is compiled against SUNDIALS 7.2.0 or newer.

Definition at line 1372 of file arkode_stepper.h.

Inheritance diagram for SUNDIALS::LSRKStepperSTS< VectorType >:

[legend]

Classes
class	AdditionalData

Public Member Functions
	LSRKStepperSTS (const AdditionalData &data=AdditionalData())

void *	get_arkode_memory () const override

Public Attributes
std::function< void(const double t, const VectorType &y, VectorType &explicit_f)>	explicit_function

std::function< std::complex< double >(const double t, const VectorType &y, const VectorType &f)>	dominant_eigenvalue_function

std::function< void(void *arkode_mem)>	custom_setup

Private Types
using	CallbackContext = typename ARKodeStepper< VectorType >::template CallbackContext< LSRKStepperSTS< VectorType > >

using	ARKodeMemoryPtr = typename ARKodeStepper< VectorType >::ARKodeMemoryPtr

Private Member Functions
void	reinit (double t0, const VectorType &y0, internal::InvocationContext inv_ctx) override

Private Attributes
AdditionalData	data

std::unique_ptr< void, void()(void )>	dom_eig_estimator

ARKodeMemoryPtr	arkode_mem

CallbackContext	callback_ctx

Member Typedef Documentation

◆ CallbackContext

template<typename VectorType = Vector<double>>

using SUNDIALS::LSRKStepperSTS< VectorType >::CallbackContext = typename ARKodeStepper< VectorType>::template CallbackContext<LSRKStepperSTS<VectorType> >

private

Definition at line 1565 of file arkode_stepper.h.

◆ ARKodeMemoryPtr

template<typename VectorType = Vector<double>>

using SUNDIALS::LSRKStepperSTS< VectorType >::ARKodeMemoryPtr = typename ARKodeStepper<VectorType>::ARKodeMemoryPtr

private

Definition at line 1568 of file arkode_stepper.h.

Constructor & Destructor Documentation

◆ LSRKStepperSTS()

template<typename VectorType = Vector<double>>

SUNDIALS::LSRKStepperSTS< VectorType >::LSRKStepperSTS ( const AdditionalData & data = AdditionalData() )

Constructor, with class parameters set by the AdditionalData object.

Parameters

data	LSRKStepperSTS configuration data

Member Function Documentation

◆ get_arkode_memory()

template<typename VectorType = Vector<double>>

void * SUNDIALS::LSRKStepperSTS< VectorType >::get_arkode_memory ( ) const

overridevirtual

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 ARKodeStepper object.

Note: If custom settings of ARKODE functionality (that are not achievable via the interface of this class) are required, the function custom_setup() should be used.

Returns: pointer to the ARKODE memory block that can be passed to SUNDIALS functions

Implements SUNDIALS::ARKodeStepper< VectorType >.

◆ reinit()

template<typename VectorType = Vector<double>>

void SUNDIALS::LSRKStepperSTS< VectorType >::reinit	(	double	t0,
		const VectorType &	y0,
		internal::InvocationContext	inv_ctx
	)

overrideprivatevirtual

Rebuild the stepper at a given time instance and for a given state vector. Required by the ARKodeStepper interface.

Parameters

t0	Time instance that serves as starting time
y0	Initial state vector whose layout is used for initialization of the internal ARKODE vectors
inv_ctx	Invocation context that provides access to the SUNContext object and the exception pointer managed by the caller

Implements SUNDIALS::ARKodeStepper< VectorType >.

Member Data Documentation

◆ explicit_function

template<typename VectorType = Vector<double>>

std::function< void(const double t, const VectorType &y, VectorType &explicit_f)> SUNDIALS::LSRKStepperSTS< VectorType >::explicit_function

A function object that users must supply and that is intended to compute the IVP right hand side. Sets \(explicit\_f = f(t, y)\).

Note: This variable represents a user provided callback. See there for a description of how to deal with errors and other requirements and conventions. In particular, ARKode can deal with "recoverable" errors in some circumstances, so callbacks can throw exceptions of type RecoverableUserCallbackError.

Definition at line 1514 of file arkode_stepper.h.

◆ dominant_eigenvalue_function

template<typename VectorType = Vector<double>>

std::function<std::complex<double>(const double t, const VectorType &y, const VectorType &f)> SUNDIALS::LSRKStepperSTS< VectorType >::dominant_eigenvalue_function

A function object that users may optionally supply and that is intended to return an estimate of the dominant (largest-magnitude) eigenvalue of the Jacobian. This information is used by SUNDIALS to determine the number of polynomial stages needed for stability.

If this callback is left unset, deal.II instead creates a SUNDIALS built-in power-iteration dominant-eigenvalue estimator (SUNDomEigEstimator) and attaches it automatically. The estimator derives the dominant eigenvalue internally from explicit_function() and requires no further input from the user. This automatic default is only available when deal.II is compiled against SUNDIALS 7.5.0 or newer; with older versions this callback must be provided.

The callback receives the current time t, the current state y, and the already-evaluated right-hand side f (i.e., \(f(t,y)\)), and returns the estimate of the dominant eigenvalue as std::complex<double>. For purely diffusive problems the imaginary part is typically zero.

Note: This variable represents a user provided callback. See there for a description of how to deal with errors and other requirements and conventions. In particular, ARKode can deal with "recoverable" errors in some circumstances, so callbacks can throw exceptions of type RecoverableUserCallbackError.

Definition at line 1546 of file arkode_stepper.h.

◆ custom_setup

template<typename VectorType = Vector<double>>

std::function<void(void *arkode_mem)> SUNDIALS::LSRKStepperSTS< 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.

Note: This function will be called at the end of all other set up right before the actual time evolution is started or continued with solve_ode(). This function is also called when the solver is restarted, see solver_should_restart(). Consult the SUNDIALS manual to see which options are still available at this point.

Parameters

arkode_mem pointer to the ARKODE memory block which can be used for custom calls to LSRKStepSet... methods.

Definition at line 1562 of file arkode_stepper.h.

◆ data

template<typename VectorType = Vector<double>>

AdditionalData SUNDIALS::LSRKStepperSTS< VectorType >::data

private

LSRKStepperSTS configuration data.

Definition at line 1588 of file arkode_stepper.h.

◆ dom_eig_estimator

template<typename VectorType = Vector<double>>

std::unique_ptr<void, void (*)(void *)> SUNDIALS::LSRKStepperSTS< VectorType >::dom_eig_estimator

private

SUNDIALS built-in dominant-eigenvalue estimator. This object is only created (and owned) when dominant_eigenvalue_function is not provided, in which case it is attached to the LSRKStep module to estimate the dominant eigenvalue automatically. Stored as an opaque pointer with a custom deleter that calls SUNDomEigEstimator_Destroy. Declared before arkode_mem so that it is destroyed after the ARKODE memory object.

Definition at line 1599 of file arkode_stepper.h.

◆ arkode_mem

template<typename VectorType = Vector<double>>

ARKodeMemoryPtr SUNDIALS::LSRKStepperSTS< VectorType >::arkode_mem

private

ARKODE memory object.

Definition at line 1605 of file arkode_stepper.h.

◆ callback_ctx

template<typename VectorType = Vector<double>>

CallbackContext SUNDIALS::LSRKStepperSTS< VectorType >::callback_ctx

private

LSRKStepperSTS callback context.

Definition at line 1610 of file arkode_stepper.h.

The documentation for this class was generated from the following file:

include/deal.II/sundials/arkode_stepper.h

Detailed Description

Classes

Public Member Functions

Public Attributes

Private Types

Private Member Functions

Private Attributes

Member Typedef Documentation

◆ CallbackContext

◆ ARKodeMemoryPtr

Constructor & Destructor Documentation

◆ LSRKStepperSTS()

Member Function Documentation

◆ get_arkode_memory()

◆ reinit()

Member Data Documentation

◆ explicit_function

◆ dominant_eigenvalue_function

◆ custom_setup

◆ data

◆ dom_eig_estimator

◆ arkode_mem

◆ callback_ctx