Exponential Runge-Kutta fixed-step time-integration for \( \dot y = A y + g(t,y)\). More...

Public Types
using	value_type = get_value_type< ContainerType >
	the value type of the time variable (float or double) More...

using	container_type = ContainerType
	the type of the vector class in use More...

Public Member Functions
	ExponentialERKStep ()=default

	ExponentialERKStep (ConvertsToFunctionalButcherTableau< value_type > tableau, const ContainerType &copyable)
	Reserve internal workspace for the integration. More...

const ContainerType &	copyable () const

template<class ExplicitRHS , class MatrixFunction >
void	step (const std::tuple< ExplicitRHS, MatrixFunction > &ode, value_type t0, const ContainerType &u0, value_type &t1, ContainerType &u1, value_type dt, ContainerType &delta)
	Advance one step with error estimate. More...

template<class ExplicitRHS , class MatrixFunction >
void	step (const std::tuple< ExplicitRHS, MatrixFunction > &ode, value_type t0, const ContainerType &u0, value_type &t1, ContainerType &u1, value_type dt)
	Advance one step ignoring error estimate and embedded method. More...

unsigned	order () const
	global order of the method given by the current Butcher Tableau More...

unsigned	embedded_order () const
	global order of the embedding given by the current Butcher Tableau More...

unsigned	num_stages () const
	number of stages of the method given by the current Butcher Tableau More...

Detailed Description

template<class ContainerType>
struct dg::mat::ExponentialERKStep< ContainerType >

Exponential Runge-Kutta fixed-step time-integration for \( \dot y = A y + g(t,y)\).

We follow Hochbruck and Ostermann, Exponential Integrators, Acta Numerica (2010)

\[ \begin{align} u^{n+1} = \exp(\Delta t A) u^n + \Delta t \sum_{i=1}^s b_i(\Delta t A) g(t^n + c_i \Delta t, U_{ni}) \\ U_{ni} = \exp(c_i\Delta t A) u^n + \Delta t \sum_{j=1}^{i-1} a_{ij}(\Delta t A) g(t^n + c_j \Delta t, U_{nj}) \end{align} \]

The method is defined by the coefficient matrix functions \(a_{ij}(z),\ b_i(z),\ c_i = \sum_{j=1}^{i-1} a_{ij}(0)\) and s is the number of stages. For \( A=0\) the underlying Runge-Kutta method with Butcher Tableau \( a_{ij} = a_{ij}(0),\ b_i=b_i(0)\) is recovered. We introduce the functions

\[ \begin{align} \varphi_{k+1}(z) := \frac{\varphi_k(z) - \varphi_k(0)}{z} \\ \varphi_0(z) = \exp(z) \end{align} \]

and the shorthand notation \( \varphi_{j,k} := \varphi_j(-c_k\Delta t A),\ \varphi_j := \varphi_j(-\Delta tA)\).

You can provide your own coefficients or use one of our predefined methods:

We follow the naming convention of the ARKode library http://runge.math.smu.edu/arkode_dev/doc/guide/build/html/Butcher.html (They also provide nice stability plots for their methods) as NAME-S-P-Q or NAME-S-Q, where

NAME is the author or name of the method
S is the number of stages in the method
P is the global order of the embedding
Q is the global order of the method

Name	Identifier	Description
Euler	dg::mat::EXPLICIT_EULER_1_1	Hochbruck and Ostermann, Exponential Integrators, Acta Numerica (2010)
Midpoint-2-2	dg::mat::MIDPOINT_2_2	Hochbruck and Ostermann, Exponential Integrators, Acta Numerica (2010)
Runge-Kutta-4-4	dg::mat::CLASSIC_4_4	Cox and Matthews, J. Comput. Phys., 176 (2002)
Hochbruck-3-3-4	dg::mat::HOCHBRUCK_3_3_4	Hochbruck and Ostermann, Exponential Integrators, Acta Numerica (2010) (The exprb43 method)

Note: In exponential Rosenbrock type schemes it is assumed that \( A\) (the matrix) is the Jacobian of the system. If it is not, then the order conditions are different and the order and embedded orders are not what is indicated in our names.

This class is usable in the dg::SinglestepTimeloop and dg::AdaptiveTimeloop

Template Parameters

ContainerType

Any class for which a specialization of TensorTraits exists and which fulfills the requirements of the there defined data and execution policies derived from AnyVectorTag and AnyPolicyTag. Among others

dg::HVec (serial), dg::DVec (cuda / omp), dg::MHVec (mpi + serial) or dg::MDVec (mpi + cuda / omp)
std::vector<dg::DVec> (vector of shared device vectors), std::array<double, 4> (array of 4 doubles) or std::map < std::string, dg::DVec> ( a map of named vectors)
double (scalar) and other primitive types ...

If there are several ContainerTypes in the argument list, then TensorTraits must exist for all of them

See also: See The dg dispatch system for a detailed explanation of our type dispatch system

Member Typedef Documentation

◆ container_type

template<class ContainerType >

using dg::mat::ExponentialERKStep< ContainerType >::container_type = ContainerType

the type of the vector class in use

◆ value_type

template<class ContainerType >

using dg::mat::ExponentialERKStep< ContainerType >::value_type = get_value_type<ContainerType>

the value type of the time variable (float or double)

Constructor & Destructor Documentation

◆ ExponentialERKStep() [1/2]

template<class ContainerType >

dg::mat::ExponentialERKStep< ContainerType >::ExponentialERKStep ( )

default

◆ ExponentialERKStep() [2/2]

template<class ContainerType >

dg::mat::ExponentialERKStep< ContainerType >::ExponentialERKStep	(	ConvertsToFunctionalButcherTableau< value_type >	tableau,
		const ContainerType &	copyable
	)

inline

Reserve internal workspace for the integration.

Parameters

tableau	Tableau, name or identifier that `ConvertsToFunctionalButcherTableau`
copyable	vector of the size that is later used in `step` ( it does not matter what values `copyable` contains, but its size is important; the `step` method can only be called with vectors of the same size)

Member Function Documentation

◆ copyable()

template<class ContainerType >

const ContainerType & dg::mat::ExponentialERKStep< ContainerType >::copyable ( ) const

inline

◆ embedded_order()

template<class ContainerType >

unsigned dg::mat::ExponentialERKStep< ContainerType >::embedded_order ( ) const

inline

global order of the embedding given by the current Butcher Tableau

◆ num_stages()

template<class ContainerType >

unsigned dg::mat::ExponentialERKStep< ContainerType >::num_stages ( ) const

inline

number of stages of the method given by the current Butcher Tableau

◆ order()

template<class ContainerType >

unsigned dg::mat::ExponentialERKStep< ContainerType >::order ( ) const

inline

global order of the method given by the current Butcher Tableau

◆ step() [1/2]

template<class ContainerType >

template<class ExplicitRHS , class MatrixFunction >

void dg::mat::ExponentialERKStep< ContainerType >::step	(	const std::tuple< ExplicitRHS, MatrixFunction > &	ode,
		value_type	t0,
		const ContainerType &	u0,
		value_type &	t1,
		ContainerType &	u1,
		value_type	dt
	)

inline

Advance one step ignoring error estimate and embedded method.

Template Parameters

ExplicitRHS The explicit (part of the) right hand side is a functor type with no return value (subroutine) of signature void operator()(value_type, const ContainerType&, ContainerType&) The first argument is the time, the second is the input vector, which the functor may not override, and the third is the output, i.e. y' = E(t, y) translates to E(t, y, y'). The two ContainerType arguments never alias each other in calls to the functor. The functor can throw to indicate failure. Exceptions should derive from std::exception.

MatrixFunction The exponential of the (part of the) right hand side is a functor type with no return value (subroutine) of signature void operator()(UnaryOp, const ContainerType&, ContainerType&) The first argument is the matrix function to compute, the second is the input vector, which the functor may not override, and the third is the output. The timestepper will call MatrixFunction(f, y, yp) where f typically is the exponential or dg::mat::phi1, dg::mat::phi2, etc. The FunctionalButcherTableau determines which matrix functions are used. The timestepper expects that MatrixFunction(f, y, yp) computes \( y' = f( A) y\). The two ContainerType arguments never alias each other in calls to the functor. The functor can throw to indicate failure. Exceptions should derive from std::exception.

Parameters

ode	the <explicit rhs, matrix_function> functor. Typically `std::tie(explicit_rhs, matrix_function)`
t0	start time
u0	value at `t0`
t1	(write only) end time ( equals `t0+dt` on return, may alias `t0`)
u1	(write only) contains result on return (may alias u0)
dt	timestep

Note: on return explicit_rhs(t1, u1) will be the last call to explicit_rhs (this is useful if ExplicitRHS holds state, which is thus updated to the current timestep)

◆ step() [2/2]

template<class ContainerType >

template<class ExplicitRHS , class MatrixFunction >

void dg::mat::ExponentialERKStep< ContainerType >::step	(	const std::tuple< ExplicitRHS, MatrixFunction > &	ode,
		value_type	t0,
		const ContainerType &	u0,
		value_type &	t1,
		ContainerType &	u1,
		value_type	dt,
		ContainerType &	delta
	)

inline

Advance one step with error estimate.

Template Parameters

ExplicitRHS The explicit (part of the) right hand side is a functor type with no return value (subroutine) of signature void operator()(value_type, const ContainerType&, ContainerType&) The first argument is the time, the second is the input vector, which the functor may not override, and the third is the output, i.e. y' = E(t, y) translates to E(t, y, y'). The two ContainerType arguments never alias each other in calls to the functor. The functor can throw to indicate failure. Exceptions should derive from std::exception.

MatrixFunction The exponential of the (part of the) right hand side is a functor type with no return value (subroutine) of signature void operator()(UnaryOp, const ContainerType&, ContainerType&) The first argument is the matrix function to compute, the second is the input vector, which the functor may not override, and the third is the output. The timestepper will call MatrixFunction(f, y, yp) where f typically is the exponential or dg::mat::phi1, dg::mat::phi2, etc. The FunctionalButcherTableau determines which matrix functions are used. The timestepper expects that MatrixFunction(f, y, yp) computes \( y' = f( A) y\). The two ContainerType arguments never alias each other in calls to the functor. The functor can throw to indicate failure. Exceptions should derive from std::exception.

Parameters

ode	the <explicit rhs, matrix_function> functor. Typically `std::tie(explicit_rhs, matrix_function)`
t0	start time
u0	value at `t0`
t1	(write only) end time ( equals `t0+dt` on return, may alias `t0`)
u1	(write only) contains result on return (may alias u0)
dt	timestep

Note: on return explicit_rhs(t1, u1) will be the last call to explicit_rhs (this is useful if ExplicitRHS holds state, which is thus updated to the current timestep)

Parameters

delta Contains error estimate (u1 - tilde u1) on return (must have equal size as u0)

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

exp_runge_kutta.h

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ container_type

◆ value_type

Constructor & Destructor Documentation

◆ ExponentialERKStep() [1/2]

◆ ExponentialERKStep() [2/2]

Member Function Documentation

◆ copyable()

◆ embedded_order()

◆ num_stages()

◆ order()

◆ step() [1/2]

◆ step() [2/2]