3.4.5.3. MRI Coupling Coefficients Data Structure

MRIStep supplies several built-in MIS, MRI-GARK, and IMEX-MRI-GARK methods, see §3.4.5.3.2 for the current set of coupling tables and their corresponding identifiers. Additionally, a user may supply a custom set of slow-to-fast time scale coupling coefficients by constructing a coupling table and attaching it with MRIStepSetCoupling().

As described in §3.2.6, the coupling from the slow time scale to the fast time scale is encoded by a vector of slow ‘stage time’ abscissae, \(c^S \in \mathbb{R}^{s+1}\) and a set of coupling matrices \(\Gamma^{\{k\}}\in\mathbb{R}^{(s+1)\times(s+1)}\) and \(\Omega^{\{k\}}\in\mathbb{R}^{(s+1)\times(s+1)}\). An MRIStepCoupling object stores this information and provides several related utility functions for creating a coupling table. The MRIStepCoupling type is defined as:

typedef MRIStepCouplingMem *MRIStepCoupling

where MRIStepCouplingMem is the structure

struct MRIStepCouplingMem
{
  int nmat;
  int stages;
  int q;
  int p;
  sunrealtype ***G;
  sunrealtype ***W;
  sunrealtype *c;
};

and the members of the strucutre are:

• nmat corresponds to the number of coupling matrices \(\Omega^{\{k\}}\) for the slow-nonstiff terms and/or \(\Gamma^{\{k\}}\) for the slow-stiff terms in (3.14),

• stages is the number of abscissae i.e., \(s+1\) above,

• q and p indicate the orders of accuracy for both the method and the embedding, respectively,

• W is a three-dimensional array with dimensions [nmat][stages][stages] containing the method’s \(\Omega^{\{k\}}\) coupling matrices for the slow-nonstiff (explicit) terms in (3.14),

• G is a three-dimensional array with dimensions [nmat][stages][stages] containing the method’s \(\Gamma^{\{k\}}\) coupling matrices for the slow-stiff (implicit) terms in (3.14), and

• c is an array of length stages containing the slow abscissae \(c^S\) for the method.

3.4.5.3.1. MRIStepCoupling functions

This section describes the functions for creating and interacting with coupling tables. The function prototypes and as well as the relevant integer constants are defined arkode/arkode_mristep.h.

Table 3.22 MRIStepCoupling functions

Function name	Description
MRIStepCoupling_LoadTable()	Loads a pre-defined MRIStepCoupling table by ID
MRIStepCoupling_LoadTableByName()	Loads a pre-defined MRIStepCoupling table by name
MRIStepCoupling_Alloc()	Allocate an empty MRIStepCoupling table
MRIStepCoupling_Create()	Create a new MRIStepCoupling table from coefficients
MRIStepCoupling_MIStoMRI()	Create a new MRIStepCoupling table from a slow Butcher table
MRIStepCoupling_Copy()	Create a copy of a MRIStepCoupling table
MRIStepCoupling_Space()	Get the MRIStepCoupling table real and integer workspace sizes
MRIStepCoupling_Free()	Deallocate a MRIStepCoupling table
MRIStepCoupling_Write()	Write the MRIStepCoupling table to an output file

MRIStepCoupling MRIStepCoupling_LoadTable(ARKODE_MRITableID method)

Retrieves a specified coupling table. For further information on the current set of coupling tables and their corresponding identifiers, see §3.4.5.3.2.

Arguments:

• method – the coupling table identifier.

Return value:

• An MRIStepCoupling structure if successful.

• A NULL pointer if method was invalid or an allocation error occurred.

MRIStepCoupling MRIStepCoupling_LoadTableByName(const char *method)

Retrieves a specified coupling table. For further information on the current set of coupling tables and their corresponding name, see §3.4.5.3.2.

Arguments:

• method – the coupling table name.

Return value:

• An MRIStepCoupling structure if successful.

• A NULL pointer if method was invalid, method was "ARKODE_MRI_NONE", or an allocation error occurred.

Note

This function is case sensitive.

MRIStepCoupling MRIStepCoupling_Alloc(int nmat, int stages, int type)

Allocates an empty MRIStepCoupling table.

Arguments:

• nmat – number of \(\Omega^{\{k\}}\) and/or \(\Gamma^{\{k\}}\) matrices in the coupling table.

• stages – number of stages in the coupling table.

• type – the method type: explicit (0), implicit (1), or ImEx (2).

Return value:

• An MRIStepCoupling structure if successful.

• A NULL pointer if stages or type was invalid or an allocation error occurred.

Note

For explicit methods only the W array is allocated, with implicit methods only the G array is allocated, and for ImEx methods both W and G are allocated.

MRIStepCoupling MRIStepCoupling_Create(int nmat, int stages, int q, int p, sunrealtype *W, sunrealtype *G, sunrealtype *c)

Allocates a coupling table and fills it with the given values.

Arguments:

• nmat – number of \(\Omega^{\{k\}}\) and/or \(\Gamma^{\{k\}}\) matrices in the coupling table.

• stages – number of stages in the method.

• q – global order of accuracy for the method.

• p – global order of accuracy for the embedded method.

• W – array of coefficients defining the explicit coupling matrices \(\Omega^{\{k\}}\). The entries should be stored as a 1D array of size nmat * stages * stages, in row-major order. If the slow method is implicit pass NULL.

• G – array of coefficients defining the implicit coupling matrices \(\Gamma^{\{k\}}\). The entries should be stored as a 1D array of size nmat * stages * stages, in row-major order. If the slow method is explicit pass NULL.

• c – array of slow abscissae for the MRI method. The entries should be stored as a 1D array of length stages.

Return value:

• An MRIStepCoupling structure if successful.

• A NULL pointer if stages was invalid, an allocation error occurred, or the input data arrays are inconsistent with the method type.

Note

As embeddings are not currently supported in MRIStep, p should be equal to zero.

MRIStepCoupling MRIStepCoupling_MIStoMRI(ARKodeButcherTable B, int q, int p)

Creates an MRI coupling table for a traditional MIS method based on the slow Butcher table B, following the formula shown in (3.16)

Arguments:

• B – the ARKodeButcherTable for the ‘slow’ MIS method.

• q – the overall order of the MIS/MRI method.

• p – the overall order of the MIS/MRI embedding.

Return value:

• An MRIStepCoupling structure if successful.

• A NULL pointer if an allocation error occurred.

Note

The \(s\)-stage slow Butcher table must have an explicit first stage (i.e., \(c_1=0\) and \(A_{1,j}=0\) for \(1\le j\le s\)) and sorted abscissae (i.e., \(c_{i} \ge c_{i-1}\) for \(2\le i\le s\)).

Since an MIS method is at most third order accurate, and even then only if it meets certain compatibility criteria (see (3.17)), the values of q and p may differ from the method and embedding orders of accuracy for the Runge–Kutta method encoded in B, which is why these arguments should be supplied separately.

As embeddings are not currently supported in MRIStep, then p should be equal to zero.

MRIStepCoupling MRIStepCoupling_Copy(MRIStepCoupling C)

Creates copy of the given coupling table.

Arguments:

• C – the coupling table to copy.

Return value:

• An MRIStepCoupling structure if successful.

• A NULL pointer if an allocation error occurred.

void MRIStepCoupling_Space(MRIStepCoupling C, sunindextype *liw, sunindextype *lrw)

Get the real and integer workspace size for a coupling table.

Arguments:

• C – the coupling table.

• lenrw – the number of sunrealtype values in the coupling table workspace.

• leniw – the number of integer values in the coupling table workspace.

Return value:

• ARK_SUCCESS if successful.

• ARK_MEM_NULL if the Butcher table memory was NULL.

void MRIStepCoupling_Free(MRIStepCoupling C)

Deallocate the coupling table memory.

Arguments:

• C – the coupling table.

void MRIStepCoupling_Write(MRIStepCoupling C, FILE *outfile)

Write the coupling table to the provided file pointer.

Arguments:

• C – the coupling table.

• outfile – pointer to use for printing the table.

Note

The outfile argument can be stdout or stderr, or it may point to a specific file created using fopen.

3.4.5.3.2. MRI Coupling Tables

MRIStep currently includes three classes of coupling tables: those that encode methods that are explicit at the slow time scale, those that are diagonally-implicit and solve-decoupled at the slow time scale, and those that encode methods with an implicit-explicit method at the slow time scale. We list the current identifiers, multirate order of accuracy, and relevant references for each in the tables below. For methods with an implicit component, we also list the number of implicit solves per step that are required at the slow time scale.

Each of the coupling tables that are packaged with MRIStep are specified by a unique ID having type:

typedef int ARKODE_MRITableID

with values specified for each method below (e.g., ARKODE_MIS_KW3).

Table 3.23 Explicit MRI-GARK coupling tables. The default method for each order is marked with an asterisk (\(^*\)).

Table name	Order	Reference
ARKODE_MIS_KW3	\(3^*\)	[105]
ARKODE_MRI_GARK_ERK33a	3	[103]
ARKODE_MRI_GARK_ERK45a	\(4^*\)	[103]

Table 3.24 Diagonally-implicit, solve-decoupled MRI-GARK coupling tables. The default method for each order is marked with an asterisk (\(^*\)).

Table name	Order	Implicit Solves	Reference
ARKODE_MRI_GARK_IRK21a	\(2^*\)	1	[103]
ARKODE_MRI_GARK_ESDIRK34a	\(3^*\)	3	[103]
ARKODE_MRI_GARK_ESDIRK46a	\(4^*\)	5	[103]

Table 3.25 Diagonally-implicit, solve-decoupled IMEX-MRI-GARK coupling tables. The default method for each order is marked with an asterisk (\(^*\)).

Table name	Order	Implicit Solves	Reference
ARKODE_IMEX_MRI_GARK3a	\(3^*\)	2	[36]
ARKODE_IMEX_MRI_GARK3b	3	2	[36]
ARKODE_IMEX_MRI_GARK4	\(4^*\)	5	[36]