3.4.4.3. MRI Coupling Coefficients Data Structure
MRIStep supplies several built-in MIS, MRI-GARK, and IMEX-MRI-GARK 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 slow-to-fast 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 slow-nonstiff terms and/or \(\Gamma^{\{k\}}\) for the slow-stiff 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 three-dimensional array with dimensions[nmat][stages][stages]
containing the method’s \(\Omega^{\{k\}}\) coupling matrices for the slow-nonstiff (explicit) terms in (3.12),
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.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 pre-defined MRIStepCoupling table |
|
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 imethod)
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:
itable
– the coupling table identifier.
- Return value:
An
MRIStepCoupling
structure if successful.A
NULL
pointer if itable was invalid or an allocation error occurred.
-
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 row-major 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 row-major 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_{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.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 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 name |
Order |
Reference |
---|---|---|
|
\(3^*\) |
[91] |
|
3 |
[89] |
|
\(4^*\) |
[89] |
Table name |
Order |
Implicit Solves |
Reference |
---|---|---|---|
|
\(2^*\) |
1 |
[89] |
|
\(3^*\) |
3 |
[89] |
|
\(4^*\) |
5 |
[89] |
Table name |
Order |
Implicit Solves |
Reference |
---|---|---|---|
|
\(3^*\) |
2 |
[34] |
|
3 |
2 |
[34] |
|
\(4^*\) |
5 |
[34] |