Interface to ARKode's ARKStep module – additive Runge-Kutta methods. More...

#include <sundials.hpp>

Inheritance diagram for mfem::ARKStepSolver:

Collaboration diagram for mfem::ARKStepSolver:

Public Types
enum	Type { EXPLICIT , IMPLICIT , IMEX }
	Types of ARKODE solvers. More...

Public Member Functions
	ARKStepSolver (Type type=EXPLICIT)
	Construct a serial wrapper to SUNDIALS' ARKode integrator.

	ARKStepSolver (MPI_Comm comm, Type type=EXPLICIT)
	Construct a parallel wrapper to SUNDIALS' ARKode integrator.

void	Init (TimeDependentOperator &f_) override
	Initialize ARKode: calls ARKStepCreate() to create the ARKStep memory and set some defaults.

void	Step (Vector &x, real_t &t, real_t &dt) override
	Integrate the ODE with ARKode using the specified step mode.

void	UseMFEMLinearSolver ()
	Attach the linear system setup and solve methods from the TimeDependentOperator i.e., SUNImplicitSetup() and SUNImplicitSolve() to ARKode.

void	UseSundialsLinearSolver ()
	Attach a SUNDIALS GMRES linear solver to ARKode.

void	UseMFEMMassLinearSolver (int tdep)
	Attach mass matrix linear system setup, solve, and matrix-vector product methods from the TimeDependentOperator i.e., SUNMassSetup(), SUNMassSolve(), and SUNMassMult() to ARKode.

void	UseSundialsMassLinearSolver (int tdep)
	Attach the SUNDIALS GMRES linear solver and the mass matrix matrix-vector product method from the TimeDependentOperator i.e., SUNMassMult() to ARKode to solve mass matrix systems.

void	SetStepMode (int itask)
	Select the ARKode step mode: ARK_NORMAL (default) or ARK_ONE_STEP.

void	SetSStolerances (double reltol, double abstol)
	Set the scalar relative and scalar absolute tolerances.

void	SetMaxStep (double dt_max)
	Set the maximum time step.

void	SetOrder (int order)
	Chooses integration order for all explicit / implicit / IMEX methods.

void	SetERKTableNum (ARKODE_ERKTableID table_id)
	Choose a specific Butcher table for an explicit RK method.

void	SetIRKTableNum (ARKODE_DIRKTableID table_id)
	Choose a specific Butcher table for a diagonally implicit RK method.

void	SetIMEXTableNum (ARKODE_ERKTableID etable_id, ARKODE_DIRKTableID itable_id)
	Choose a specific Butcher table for an IMEX RK method.

void	SetFixedStep (double dt)
	Use a fixed time step size (disable temporal adaptivity).

void	PrintInfo () const
	Print various ARKStep statistics.

virtual	~ARKStepSolver ()
	Destroy the associated ARKode memory and SUNDIALS objects.

Public Member Functions inherited from mfem::ODESolver
	ODESolver ()

virtual void	Run (Vector &x, real_t &t, real_t &dt, real_t tf)
	Perform time integration from time t [in] to time tf [in].

virtual int	GetStateSize ()
	Returns how many State vectors the ODE requires.

virtual	~ODESolver ()

Public Member Functions inherited from mfem::SundialsSolver
void *	GetMem () const
	Access the SUNDIALS memory structure.

int	GetFlag () const
	Returns the last flag returned by a call to a SUNDIALS function.

Static Protected Member Functions
static int	LinSysSetup (sunrealtype t, N_Vector y, N_Vector fy, SUNMatrix A, SUNMatrix M, sunbooleantype jok, sunbooleantype jcur, sunrealtype gamma, void user_data, N_Vector tmp1, N_Vector tmp2, N_Vector tmp3)
	Setup the linear system \( A x = b \).

static int	LinSysSolve (SUNLinearSolver LS, SUNMatrix A, N_Vector x, N_Vector b, sunrealtype tol)
	Solve the linear system \( A x = b \).

static int	MassSysSetup (sunrealtype t, SUNMatrix M, void *user_data, N_Vector tmp1, N_Vector tmp2, N_Vector tmp3)
	Setup the linear system \( M x = b \).

static int	MassSysSolve (SUNLinearSolver LS, SUNMatrix M, N_Vector x, N_Vector b, sunrealtype tol)
	Solve the linear system \( M x = b \).

static int	MassMult1 (SUNMatrix M, N_Vector x, N_Vector v)
	Compute the matrix-vector product \( v = M x \).

static int	MassMult2 (N_Vector x, N_Vector v, sunrealtype t, void *mtimes_data)
	Compute the matrix-vector product \(v = M_t x \) at time t.

Wrappers to compute the ODE RHS functions.
RHS1 is explicit RHS and RHS2 the implicit RHS for IMEX integration. When purely implicit or explicit only RHS1 is used.
static int	RHS1 (sunrealtype t, const N_Vector y, N_Vector ydot, void *user_data)

static int	RHS2 (sunrealtype t, const N_Vector y, N_Vector ydot, void *user_data)

Protected Attributes
Type	rk_type
	Runge-Kutta type.

int	step_mode
	ARKStep step mode (ARK_NORMAL or ARK_ONE_STEP).

bool	use_implicit
	True for implicit or imex integration.

Protected Attributes inherited from mfem::ODESolver
TimeDependentOperator *	f
	Pointer to the associated TimeDependentOperator.

MemoryType	mem_type

Protected Attributes inherited from mfem::SundialsSolver
void *	sundials_mem
	SUNDIALS mem structure.

int	flag
	Last flag returned from a call to SUNDIALS.

bool	reinit
	Flag to signal memory reinitialization is need.

long	saved_global_size
	Global vector length on last initialization.

SundialsNVector *	Y
	State vector.

SUNMatrix	A

SUNMatrix	M
	Mass matrix M.

SUNLinearSolver	LSA
	Linear solver for A.

SUNLinearSolver	LSM
	Linear solver for M.

SUNNonlinearSolver	NLS
	Nonlinear solver.

Additional Inherited Members
Static Public Member Functions inherited from mfem::ODESolver
static MFEM_EXPORT std::unique_ptr< ODESolver >	Select (const int ode_solver_type)

static MFEM_EXPORT std::unique_ptr< ODESolver >	SelectExplicit (const int ode_solver_type)

static MFEM_EXPORT std::unique_ptr< ODESolver >	SelectImplicit (const int ode_solver_type)

Static Public Attributes inherited from mfem::ODESolver
static MFEM_EXPORT std::string	ExplicitTypes

static MFEM_EXPORT std::string	ImplicitTypes

static MFEM_EXPORT std::string	Types

Protected Member Functions inherited from mfem::SundialsSolver
bool	Parallel () const

bool	Parallel () const

	SundialsSolver ()
	Protected constructor: objects of this type should be constructed only as part of a derived class.

void	AllocateEmptyNVector (N_Vector &y)

void	AllocateEmptyNVector (N_Vector &y, MPI_Comm comm)

Static Protected Attributes inherited from mfem::SundialsSolver
static constexpr double	default_rel_tol = 1e-4
	Default scalar relative tolerance.

static constexpr double	default_abs_tol = 1e-9
	Default scalar absolute tolerance.

Detailed Description

Interface to ARKode's ARKStep module – additive Runge-Kutta methods.

Definition at line 710 of file sundials.hpp.

Member Enumeration Documentation

◆ Type

enum mfem::ARKStepSolver::Type

Types of ARKODE solvers.

Enumerator
EXPLICIT	Explicit RK method.
IMPLICIT	Implicit RK method.
IMEX	Implicit-explicit ARK method.

Definition at line 714 of file sundials.hpp.

Constructor & Destructor Documentation

◆ ARKStepSolver() [1/2]

mfem::ARKStepSolver::ARKStepSolver ( Type type = EXPLICIT )

Construct a serial wrapper to SUNDIALS' ARKode integrator.

Parameters

[in]

type

Specifies the RK method type:

EXPLICIT - explicit RK method (default)
IMPLICIT - implicit RK method
IMEX - implicit-explicit ARK method

Definition at line 1505 of file sundials.cpp.

◆ ARKStepSolver() [2/2]

mfem::ARKStepSolver::ARKStepSolver	(	MPI_Comm	comm,
		Type	type = EXPLICIT )

Construct a parallel wrapper to SUNDIALS' ARKode integrator.

Parameters

[in]	comm	The MPI communicator used to partition the ODE system.
[in]	type	Specifies the RK method type: EXPLICIT - explicit RK method (default) IMPLICIT - implicit RK method IMEX - implicit-explicit ARK method

Definition at line 1513 of file sundials.cpp.

◆ ~ARKStepSolver()

mfem::ARKStepSolver::~ARKStepSolver ( )

virtual

Destroy the associated ARKode memory and SUNDIALS objects.

Definition at line 1877 of file sundials.cpp.

Member Function Documentation

◆ Init()

void mfem::ARKStepSolver::Init ( TimeDependentOperator & f_ )

overridevirtual

Initialize ARKode: calls ARKStepCreate() to create the ARKStep memory and set some defaults.

If the ARKStep has already been created, it checks if the problem size has changed since the last call to Init(). If the problem is the same then ARKStepReInit() will be called in the next call to Step(). If the problem size has changed, the ARKStep memory is freed and realloced for the new problem size.

Parameters

[in] f_ The TimeDependentOperator that defines the ODE system

Note: All other methods must be called after Init().; If this method is called a second time with a different problem size, then any non-default user-set options will be lost and will need to be set again.

Reimplemented from mfem::ODESolver.

Definition at line 1521 of file sundials.cpp.

◆ LinSysSetup()

int mfem::ARKStepSolver::LinSysSetup	(	sunrealtype	t,
		N_Vector	y,
		N_Vector	fy,
		SUNMatrix	A,
		SUNMatrix	M,
		sunbooleantype	jok,
		sunbooleantype *	jcur,
		sunrealtype	gamma,
		void *	user_data,
		N_Vector	tmp1,
		N_Vector	tmp2,
		N_Vector	tmp3 )

staticprotected

Setup the linear system \( A x = b \).

Definition at line 1428 of file sundials.cpp.

◆ LinSysSolve()

int mfem::ARKStepSolver::LinSysSolve	(	SUNLinearSolver	LS,
		SUNMatrix	A,
		N_Vector	x,
		N_Vector	b,
		sunrealtype	tol )

staticprotected

Solve the linear system \( A x = b \).

Definition at line 1447 of file sundials.cpp.

◆ MassMult1()

int mfem::ARKStepSolver::MassMult1	(	SUNMatrix	M,
		N_Vector	x,
		N_Vector	v )

staticprotected

Compute the matrix-vector product \( v = M x \).

Definition at line 1483 of file sundials.cpp.

◆ MassMult2()

int mfem::ARKStepSolver::MassMult2	(	N_Vector	x,
		N_Vector	v,
		sunrealtype	t,
		void *	mtimes_data )

staticprotected

Compute the matrix-vector product \(v = M_t x \) at time t.

Definition at line 1493 of file sundials.cpp.

◆ MassSysSetup()

int mfem::ARKStepSolver::MassSysSetup	(	sunrealtype	t,
		SUNMatrix	M,
		void *	user_data,
		N_Vector	tmp1,
		N_Vector	tmp2,
		N_Vector	tmp3 )

staticprotected

Setup the linear system \( M x = b \).

Definition at line 1462 of file sundials.cpp.

◆ MassSysSolve()

int mfem::ARKStepSolver::MassSysSolve	(	SUNLinearSolver	LS,
		SUNMatrix	M,
		N_Vector	x,
		N_Vector	b,
		sunrealtype	tol )

staticprotected

Solve the linear system \( M x = b \).

Definition at line 1472 of file sundials.cpp.

◆ PrintInfo()

void mfem::ARKStepSolver::PrintInfo ( ) const

Print various ARKStep statistics.

Definition at line 1824 of file sundials.cpp.

◆ RHS1()

int mfem::ARKStepSolver::RHS1	(	sunrealtype	t,
		const N_Vector	y,
		N_Vector	ydot,
		void *	user_data )

staticprotected

Definition at line 1370 of file sundials.cpp.

◆ RHS2()

int mfem::ARKStepSolver::RHS2	(	sunrealtype	t,
		const N_Vector	y,
		N_Vector	ydot,
		void *	user_data )

staticprotected

Definition at line 1402 of file sundials.cpp.

◆ SetERKTableNum()

void mfem::ARKStepSolver::SetERKTableNum ( ARKODE_ERKTableID table_id )

Choose a specific Butcher table for an explicit RK method.

See ARKODE documentation for all possible options, stability regions, etc. For example, table_id = BOGACKI_SHAMPINE_4_2_3 is 4-stage 3rd order.

Definition at line 1798 of file sundials.cpp.

◆ SetFixedStep()

void mfem::ARKStepSolver::SetFixedStep ( double dt )

Use a fixed time step size (disable temporal adaptivity).

Use of this function is not recommended, since there is no assurance of the validity of the computed solutions. It is primarily provided for code-to-code verification testing purposes.

Definition at line 1817 of file sundials.cpp.

◆ SetIMEXTableNum()

void mfem::ARKStepSolver::SetIMEXTableNum	(	ARKODE_ERKTableID	etable_id,
		ARKODE_DIRKTableID	itable_id )

Choose a specific Butcher table for an IMEX RK method.

See ARKODE documentation for all possible options, stability regions, etc. For example, etable_id = ARK548L2SA_DIRK_8_4_5 and itable_id = ARK548L2SA_ERK_8_4_5 is 8-stage 5th order.

Definition at line 1810 of file sundials.cpp.

◆ SetIRKTableNum()

void mfem::ARKStepSolver::SetIRKTableNum ( ARKODE_DIRKTableID table_id )

Choose a specific Butcher table for a diagonally implicit RK method.

See ARKODE documentation for all possible options, stability regions, etc. For example, table_id = CASH_5_3_4 is 5-stage 4th order.

Definition at line 1804 of file sundials.cpp.

◆ SetMaxStep()

void mfem::ARKStepSolver::SetMaxStep ( double dt_max )

Set the maximum time step.

Definition at line 1784 of file sundials.cpp.

◆ SetOrder()

void mfem::ARKStepSolver::SetOrder ( int order )

Chooses integration order for all explicit / implicit / IMEX methods.

The default is 4, and the allowed ranges are: [2, 8] for explicit; [2, 5] for implicit; [3, 5] for IMEX.

Definition at line 1791 of file sundials.cpp.

◆ SetSStolerances()

void mfem::ARKStepSolver::SetSStolerances	(	double	reltol,
		double	abstol )

Set the scalar relative and scalar absolute tolerances.

Definition at line 1777 of file sundials.cpp.

◆ SetStepMode()

void mfem::ARKStepSolver::SetStepMode ( int itask )

Select the ARKode step mode: ARK_NORMAL (default) or ARK_ONE_STEP.

Parameters

[in] itask The desired step mode

Definition at line 1772 of file sundials.cpp.

◆ Step()

void mfem::ARKStepSolver::Step	(	Vector &	x,
		real_t &	t,
		real_t &	dt )

overridevirtual

Integrate the ODE with ARKode using the specified step mode.

Parameters

[in,out]	x	On output, the solution vector at the requested output time, tout = t + dt
[in,out]	t	On output, the output time reached
[in,out]	dt	On output, the last time step taken

Note: On input, the values of t and dt are used to compute desired output time for the integration, tout = t + dt.

Implements mfem::ODESolver.

Definition at line 1620 of file sundials.cpp.

◆ UseMFEMLinearSolver()

void mfem::ARKStepSolver::UseMFEMLinearSolver ( )

Attach the linear system setup and solve methods from the TimeDependentOperator i.e., SUNImplicitSetup() and SUNImplicitSolve() to ARKode.

Definition at line 1661 of file sundials.cpp.

◆ UseMFEMMassLinearSolver()

void mfem::ARKStepSolver::UseMFEMMassLinearSolver ( int tdep )

Attach mass matrix linear system setup, solve, and matrix-vector product methods from the TimeDependentOperator i.e., SUNMassSetup(), SUNMassSolve(), and SUNMassMult() to ARKode.

Parameters

[in] tdep An integer flag indicating if the mass matrix is time dependent (1) or time independent (0)

Definition at line 1710 of file sundials.cpp.

◆ UseSundialsLinearSolver()

void mfem::ARKStepSolver::UseSundialsLinearSolver ( )

Attach a SUNDIALS GMRES linear solver to ARKode.

Definition at line 1694 of file sundials.cpp.

◆ UseSundialsMassLinearSolver()

void mfem::ARKStepSolver::UseSundialsMassLinearSolver ( int tdep )

Attach the SUNDIALS GMRES linear solver and the mass matrix matrix-vector product method from the TimeDependentOperator i.e., SUNMassMult() to ARKode to solve mass matrix systems.

Parameters

[in] tdep An integer flag indicating if the mass matrix is time dependent (1) or time independent (0)

Definition at line 1747 of file sundials.cpp.

Member Data Documentation

◆ rk_type

Type mfem::ARKStepSolver::rk_type

protected

Runge-Kutta type.

Definition at line 722 of file sundials.hpp.

◆ step_mode

int mfem::ARKStepSolver::step_mode

protected

ARKStep step mode (ARK_NORMAL or ARK_ONE_STEP).

Definition at line 723 of file sundials.hpp.

◆ use_implicit

bool mfem::ARKStepSolver::use_implicit

protected

True for implicit or imex integration.

Definition at line 724 of file sundials.hpp.

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

linalg/sundials.hpp
linalg/sundials.cpp

Public Types

Public Member Functions

Static Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ Type

Constructor & Destructor Documentation

◆ ARKStepSolver() [1/2]

◆ ARKStepSolver() [2/2]

◆ ~ARKStepSolver()

Member Function Documentation

◆ Init()

◆ LinSysSetup()

◆ LinSysSolve()

◆ MassMult1()

◆ MassMult2()

◆ MassSysSetup()

◆ MassSysSolve()

◆ PrintInfo()

◆ RHS1()

◆ RHS2()

◆ SetERKTableNum()

◆ SetFixedStep()

◆ SetIMEXTableNum()

◆ SetIRKTableNum()

◆ SetMaxStep()

◆ SetOrder()

◆ SetSStolerances()

◆ SetStepMode()

◆ Step()

◆ UseMFEMLinearSolver()

◆ UseMFEMMassLinearSolver()

◆ UseSundialsLinearSolver()

◆ UseSundialsMassLinearSolver()

Member Data Documentation

◆ rk_type

◆ step_mode

◆ use_implicit