SUNDIALS::ERKStepper< VectorType > Class Template Reference

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

Detailed Description

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

The class provides a wrapper to ERKStep time-stepping module.

ERKStep solves ODE initial value problems (IVPs) in \(R^N\) using explicit Runge-Kutta methods. These problems should be posed as

\[ \dot y = f(t, y), \qquad y(t_0) = y_0. \]

Here, \(t\) is the independent variable (e.g. time), \(y \in R^N\) are the dependent variables, and \(\dot y\) denotes \(dy/dt\).

ERKStep is intended for non-stiff problems. For stiff or multi-rate problems consider using ARKStepper instead.

ERKStep allows orders of accuracy \(q = \{2, 3, 4, 5, 6, 8\}\), with embeddings of orders \(p = \{1, 2, 3, 4, 5, 7\}\). These default to the Heun-Euler-2-1-2, Bogacki-Shampine-4-2-3, Zonneveld-5-3-4, Cash-Karp-6-4-5, Verner-8-5-6 and Fehlberg-13-7-8 methods, respectively.

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

• explicit_function()

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

• custom_setup()

To provide a simple example, consider the harmonic oscillator problem:

\[ \begin{split} u'' & = -k^2 u \\ u (0) & = 0 \\ u'(0) & = k \end{split} \]

We write it in terms of a first order ode:

\[ \begin{matrix} y_0' & = y_1 \\ y_1' & = - k^2 y_0 \end{matrix} \]

A minimal implementation is given by the following code snippet:

using VectorType = Vector<double>;
 
SUNDIALS::ERKStepper<VectorType> stepper;
SUNDIALS::ARKode<VectorType> ode(stepper);
 
const double k = 1.0;
 
stepper.explicit_function = [k](const double / * time * /,
                                const VectorType &y,
                                VectorType &ydot)
{
  ydot[0] = y[1];
  ydot[1] = -k*k*y[0];
};
 
Vector<double> y(2);
y[1] = k;
 
ode.solve_ode(y);

Definition at line 1210 of file arkode_stepper.h.

Inheritance diagram for SUNDIALS::ERKStepper< VectorType >:

Classes
class	AdditionalData

Public Member Functions
	ERKStepper (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< void(void *arkode_mem)>	custom_setup

Protected Member Functions
internal::InvocationContext	invocation_context () const

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

Private Member Functions
void	reinit (double t0, const VectorType &y0) override
void	resize (double t0, const VectorType &y0, double hscale) override
void	attach (std::exception_ptr &pending_exception, const internal::SharedSUNContext &context)

Private Attributes
AdditionalData	data
ARKodeMemoryPtr	arkode_mem
CallbackContext	callback_ctx
std::exception_ptr *	pending_exception_ptr = nullptr
internal::SharedSUNContext	sundials_context

Member Typedef Documentation

CallbackContext

template<typename VectorType = Vector<double>>

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

private

Definition at line 1329 of file arkode_stepper.h.

ARKodeMemoryPtr

template<typename VectorType = Vector<double>>

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

private

Definition at line 1332 of file arkode_stepper.h.

Constructor & Destructor Documentation

ERKStepper()

template<typename VectorType = Vector<double>>

SUNDIALS::ERKStepper< VectorType >::ERKStepper

(

const AdditionalData &

data = AdditionalData()

)

Constructor, with class parameters set by the AdditionalData object.

Parameters

data	ERKStep configuration data

Member Function Documentation

get_arkode_memory()

template<typename VectorType = Vector<double>>

void * SUNDIALS::ERKStepper< 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::ERKStepper< VectorType >::reinit ( double  t0, const VectorType &  y0  )

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

Implements SUNDIALS::ARKodeStepper< VectorType >.

resize()

template<typename VectorType = Vector<double>>

void SUNDIALS::ERKStepper< VectorType >::resize ( double  t0, const VectorType &  y0, double  hscale  )

overrideprivatevirtual

Resize the ARKODE memory in place via ARKodeResize()/ERKStepResize().

Parameters

t0	Current time
y0	Current state vector with the new size
hscale	Factor by which the upcoming step size is rescaled; values less or equal to zero are treated as one

Implements SUNDIALS::ARKodeStepper< VectorType >.

attach()

template<typename VectorType >

void SUNDIALS::ARKodeStepper< VectorType >::attach ( std::exception_ptr &  pending_exception, const internal::SharedSUNContext &  context  )

inlineprivateinherited

Bind the stepper to the ARKode object that drives it. This is called once by the constructor of ARKode. All objects the stepper creates for SUNDIALS use context, which the stepper keeps alive for as long as it lives, and callbacks store exceptions in pending_exception.

Note

A stepper can be attached to a single ARKode object only.

Definition at line 125 of file arkode_stepper.h.

invocation_context()

template<typename VectorType >

internal::InvocationContext SUNDIALS::ARKodeStepper< VectorType >::invocation_context ( ) const

inlineprotectedinherited

The context that the ARKode object, to which this stepper is attached. It is used to create SUNDIALS objects and to propagate exceptions across C boundaries (see invocation_context.h).

Definition at line 193 of file arkode_stepper.h.

Member Data Documentation

explicit_function

template<typename VectorType = Vector<double>>

std::function< void(const double t, const VectorType &y, VectorType &explicit_f)> SUNDIALS::ERKStepper< 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 1299 of file arkode_stepper.h.

custom_setup

template<typename VectorType = Vector<double>>

std::function<void(void *arkode_mem)> SUNDIALS::ERKStepper< 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 selects a specific built-in Butcher table for the ERK method:

stepper.custom_setup = [&](void *arkode_mem) {
  const int status = ERKStepSetTableName(
    arkode_mem, explicit_method_name);
  AssertARKode(status);
};

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 ERKStepSet... methods.

Definition at line 1326 of file arkode_stepper.h.

data

template<typename VectorType = Vector<double>>

AdditionalData SUNDIALS::ERKStepper< VectorType >::data

private

ERKStepper configuration data.

Definition at line 1359 of file arkode_stepper.h.

arkode_mem

template<typename VectorType = Vector<double>>

ARKodeMemoryPtr SUNDIALS::ERKStepper< VectorType >::arkode_mem

private

ARKODE memory object.

Definition at line 1364 of file arkode_stepper.h.

callback_ctx

template<typename VectorType = Vector<double>>

CallbackContext SUNDIALS::ERKStepper< VectorType >::callback_ctx

private

ERKStepper callback context.

Definition at line 1369 of file arkode_stepper.h.

pending_exception_ptr

template<typename VectorType >

std::exception_ptr* SUNDIALS::ARKodeStepper< VectorType >::pending_exception_ptr = nullptr

privateinherited

Exception pointer of the ARKode object this stepper is attached to.

Definition at line 211 of file arkode_stepper.h.

sundials_context

template<typename VectorType >

internal::SharedSUNContext SUNDIALS::ARKodeStepper< VectorType >::sundials_context

privateinherited

Base class members are destroyed after those of derived classes, so the context outlives the ARKODE memory and everything else a derived stepper created with it.

Definition at line 219 of file arkode_stepper.h.

---

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

• include/deal.II/sundials/arkode_stepper.h