MFEM  v4.5.2
Finite element discretization library
Public Types | Public Member Functions | Static Protected Member Functions | Protected Attributes | List of all members
mfem::ARKStepSolver Class Reference

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

#include <sundials.hpp>

Inheritance diagram for mfem::ARKStepSolver:
[legend]
Collaboration diagram for mfem::ARKStepSolver:
[legend]

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. More...
 
 ARKStepSolver (MPI_Comm comm, Type type=EXPLICIT)
 Construct a parallel wrapper to SUNDIALS' ARKode integrator. More...
 
void Init (TimeDependentOperator &f_)
 Initialize ARKode: calls ARKStepCreate() to create the ARKStep memory and set some defaults. More...
 
virtual void Step (Vector &x, double &t, double &dt)
 Integrate the ODE with ARKode using the specified step mode. More...
 
void UseMFEMLinearSolver ()
 Attach the linear system setup and solve methods from the TimeDependentOperator i.e., SUNImplicitSetup() and SUNImplicitSolve() to ARKode. More...
 
void UseSundialsLinearSolver ()
 Attach a SUNDIALS GMRES linear solver to ARKode. More...
 
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. More...
 
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. More...
 
void SetStepMode (int itask)
 Select the ARKode step mode: ARK_NORMAL (default) or ARK_ONE_STEP. More...
 
void SetSStolerances (double reltol, double abstol)
 Set the scalar relative and scalar absolute tolerances. More...
 
void SetMaxStep (double dt_max)
 Set the maximum time step. More...
 
void SetOrder (int order)
 Chooses integration order for all explicit / implicit / IMEX methods. More...
 
void SetERKTableNum (ARKODE_ERKTableID table_id)
 Choose a specific Butcher table for an explicit RK method. More...
 
void SetIRKTableNum (ARKODE_DIRKTableID table_id)
 Choose a specific Butcher table for a diagonally implicit RK method. More...
 
void SetIMEXTableNum (ARKODE_ERKTableID etable_id, ARKODE_DIRKTableID itable_id)
 Choose a specific Butcher table for an IMEX RK method. More...
 
void SetFixedStep (double dt)
 Use a fixed time step size (disable temporal adaptivity). More...
 
void PrintInfo () const
 Print various ARKStep statistics. More...
 
virtual ~ARKStepSolver ()
 Destroy the associated ARKode memory and SUNDIALS objects. More...
 
- Public Member Functions inherited from mfem::ODESolver
 ODESolver ()
 
virtual void Run (Vector &x, double &t, double &dt, double tf)
 Perform time integration from time t [in] to time tf [in]. More...
 
virtual int GetMaxStateSize ()
 Function for getting and setting the state vectors. More...
 
virtual int GetStateSize ()
 
virtual const VectorGetStateVector (int i)
 
virtual void GetStateVector (int i, Vector &state)
 
virtual void SetStateVector (int i, Vector &state)
 
virtual ~ODESolver ()
 
- Public Member Functions inherited from mfem::SundialsSolver
void * GetMem () const
 Access the SUNDIALS memory structure. More...
 
int GetFlag () const
 Returns the last flag returned by a call to a SUNDIALS function. More...
 

Static Protected Member Functions

static int LinSysSetup (realtype t, N_Vector y, N_Vector fy, SUNMatrix A, SUNMatrix M, booleantype jok, booleantype *jcur, realtype gamma, void *user_data, N_Vector tmp1, N_Vector tmp2, N_Vector tmp3)
 Setup the linear system \( A x = b \). More...
 
static int LinSysSolve (SUNLinearSolver LS, SUNMatrix A, N_Vector x, N_Vector b, realtype tol)
 Solve the linear system \( A x = b \). More...
 
static int MassSysSetup (realtype t, SUNMatrix M, void *user_data, N_Vector tmp1, N_Vector tmp2, N_Vector tmp3)
 Setup the linear system \( M x = b \). More...
 
static int MassSysSolve (SUNLinearSolver LS, SUNMatrix M, N_Vector x, N_Vector b, realtype tol)
 Solve the linear system \( M x = b \). More...
 
static int MassMult1 (SUNMatrix M, N_Vector x, N_Vector v)
 Compute the matrix-vector product \( v = M x \). More...
 
static int MassMult2 (N_Vector x, N_Vector v, realtype t, void *mtimes_data)
 Compute the matrix-vector product \(v = M_t x \) at time t. More...
 
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 (realtype t, const N_Vector y, N_Vector ydot, void *user_data)
 
static int RHS2 (realtype t, const N_Vector y, N_Vector ydot, void *user_data)
 

Protected Attributes

Type rk_type
 Runge-Kutta type. More...
 
int step_mode
 ARKStep step mode (ARK_NORMAL or ARK_ONE_STEP). More...
 
bool use_implicit
 True for implicit or imex integration. More...
 
- Protected Attributes inherited from mfem::ODESolver
TimeDependentOperatorf
 Pointer to the associated TimeDependentOperator. More...
 
MemoryType mem_type
 
- Protected Attributes inherited from mfem::SundialsSolver
void * sundials_mem
 SUNDIALS mem structure. More...
 
int flag
 Last flag returned from a call to SUNDIALS. More...
 
bool reinit
 Flag to signal memory reinitialization is need. More...
 
long saved_global_size
 Global vector length on last initialization. More...
 
SundialsNVectorY
 State vector. More...
 
SUNMatrix A
 
SUNMatrix M
 Mass matrix M. More...
 
SUNLinearSolver LSA
 Linear solver for A. More...
 
SUNLinearSolver LSM
 Linear solver for M. More...
 
SUNNonlinearSolver NLS
 Nonlinear solver. More...
 

Additional Inherited Members

- 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. More...
 
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. More...
 
static constexpr double default_abs_tol = 1e-9
 Default scalar absolute tolerance. More...
 

Detailed Description

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

Definition at line 661 of file sundials.hpp.

Member Enumeration Documentation

◆ Type

Types of ARKODE solvers.

Enumerator
EXPLICIT 

Explicit RK method.

IMPLICIT 

Implicit RK method.

IMEX 

Implicit-explicit ARK method.

Definition at line 665 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]typeSpecifies the RK method type:
  • EXPLICIT - explicit RK method (default)
  • IMPLICIT - implicit RK method
  • IMEX - implicit-explicit ARK method

Definition at line 1445 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]commThe MPI communicator used to partition the ODE system.
[in]typeSpecifies the RK method type:
  • EXPLICIT - explicit RK method (default)
  • IMPLICIT - implicit RK method
  • IMEX - implicit-explicit ARK method

Definition at line 1453 of file sundials.cpp.

◆ ~ARKStepSolver()

mfem::ARKStepSolver::~ARKStepSolver ( )
virtual

Destroy the associated ARKode memory and SUNDIALS objects.

Definition at line 1795 of file sundials.cpp.

Member Function Documentation

◆ Init()

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

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 1461 of file sundials.cpp.

◆ LinSysSetup()

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

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

Definition at line 1368 of file sundials.cpp.

◆ LinSysSolve()

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

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

Definition at line 1387 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 1423 of file sundials.cpp.

◆ MassMult2()

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

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

Definition at line 1433 of file sundials.cpp.

◆ MassSysSetup()

int mfem::ARKStepSolver::MassSysSetup ( realtype  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 1402 of file sundials.cpp.

◆ MassSysSolve()

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

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

Definition at line 1412 of file sundials.cpp.

◆ PrintInfo()

void mfem::ARKStepSolver::PrintInfo ( ) const

Print various ARKStep statistics.

Definition at line 1743 of file sundials.cpp.

◆ RHS1()

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

Definition at line 1331 of file sundials.cpp.

◆ RHS2()

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

Definition at line 1351 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 1718 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 1737 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 1730 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 1724 of file sundials.cpp.

◆ SetMaxStep()

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

Set the maximum time step.

Definition at line 1706 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 1712 of file sundials.cpp.

◆ SetSStolerances()

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

Set the scalar relative and scalar absolute tolerances.

Definition at line 1700 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]itaskThe desired step mode

Definition at line 1695 of file sundials.cpp.

◆ Step()

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

Integrate the ODE with ARKode using the specified step mode.

Parameters
[in,out]xOn output, the solution vector at the requested output time, tout = t + dt
[in,out]tOn output, the output time reached
[in,out]dtOn 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 1557 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 1597 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]tdepAn integer flag indicating if the mass matrix is time dependent (1) or time independent (0)

Definition at line 1643 of file sundials.cpp.

◆ UseSundialsLinearSolver()

void mfem::ARKStepSolver::UseSundialsLinearSolver ( )

Attach a SUNDIALS GMRES linear solver to ARKode.

Definition at line 1628 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]tdepAn integer flag indicating if the mass matrix is time dependent (1) or time independent (0)

Definition at line 1675 of file sundials.cpp.

Member Data Documentation

◆ rk_type

Type mfem::ARKStepSolver::rk_type
protected

Runge-Kutta type.

Definition at line 673 of file sundials.hpp.

◆ step_mode

int mfem::ARKStepSolver::step_mode
protected

ARKStep step mode (ARK_NORMAL or ARK_ONE_STEP).

Definition at line 674 of file sundials.hpp.

◆ use_implicit

bool mfem::ARKStepSolver::use_implicit
protected

True for implicit or imex integration.

Definition at line 675 of file sundials.hpp.


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