3.4.4.3. MRI Coupling Coefficients Data Structure
MRIStep supplies several builtin MIS, MRIGARK, and IMEXMRIGARK methods, see
§3.4.4.3.2 for the current set of coupling
tables and their corresponding identifiers. Additionally, a user may supply a
custom set of slowtofast time scale coupling coefficients by constructing a
coupling table and attaching it with MRIStepSetCoupling()
.
As described in §3.2.5, 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;
realtype ***G;
realtype ***W;
realtype *c;
};
and the members of the strucutre are:
nmat
corresponds to the number of coupling matrices \(\Omega^{\{k\}}\) for the slownonstiff terms and/or \(\Gamma^{\{k\}}\) for the slowstiff terms in (3.12),
stages
is the number of abscissae i.e., \(s+1\) above,
q
andp
indicate the orders of accuracy for both the method and the embedding, respectively,
W
is a threedimensional array with dimensions[nmat][stages][stages]
containing the method’s \(\Omega^{\{k\}}\) coupling matrices for the slownonstiff (explicit) terms in (3.12),
G
is a threedimensional array with dimensions[nmat][stages][stages]
containing the method’s \(\Gamma^{\{k\}}\) coupling matrices for the slowstiff (implicit) terms in (3.12), and
c
is an array of lengthstages
containing the slow abscissae \(c^S\) for the method.
3.4.4.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
.
Function name 
Description 
Loads a predefined MRIStepCoupling table by ID 

Loads a predefined MRIStepCoupling table by name 

Allocate an empty MRIStepCoupling table 

Create a new MRIStepCoupling table from coefficients 

Create a new MRIStepCoupling table from a slow Butcher table 

Create a copy of a MRIStepCoupling table 

Get the MRIStepCoupling table real and integer workspace sizes 

Deallocate a MRIStepCoupling table 

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.4.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.4.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, realtype *W, realtype *G, realtype *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 sizenmat * stages * stages
, in rowmajor order. If the slow method is implicit passNULL
.G
– array of coefficients defining the implicit coupling matrices \(\Gamma^{\{k\}}\). The entries should be stored as a 1D array of sizenmat * stages * stages
, in rowmajor order. If the slow method is explicit passNULL
.c
– array of slow abscissae for the MRI method. The entries should be stored as a 1D array of lengthstages
.
 Return value:
An
MRIStepCoupling
structure if successful.A
NULL
pointer ifstages
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.14)
 Arguments:
B
– theARKodeButcherTable
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_{i1}\) 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.15)), 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 ofrealtype
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
orstderr
, or it may point to a specific file created usingfopen
.
3.4.4.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 diagonallyimplicit and solvedecoupled at the slow time scale, and those that encode methods with an implicitexplicit 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 name 
Order 
Reference 


\(3^*\) 
[93] 

3 
[91] 

\(4^*\) 
[91] 
Table name 
Order 
Implicit Solves 
Reference 


\(2^*\) 
1 
[91] 

\(3^*\) 
3 
[91] 

\(4^*\) 
5 
[91] 
Table name 
Order 
Implicit Solves 
Reference 


\(3^*\) 
2 
[35] 

3 
2 
[35] 

\(4^*\) 
5 
[35] 