Butcher Table Data Structure¶

To store the Butcher table defining a Runge Kutta method ARKode provides the ARKodeButcherTable type and several related utilitiy routines. We use the following Butcher table notation (shown for a 3-stage method):

$\begin{split}\begin{array}{r|c} c & A \\ \hline q & b \\ p & \tilde{b} \end{array} = \begin{array}{r|ccc} c_1 & a_{1,1} & a_{1,2} & a_{1,3} \\ c_2 & a_{2,1} & a_{2,2} & a_{2,3} \\ c_3 & a_{3,1} & a_{3,2} & a_{3,3} \\ \hline q & b_1 & b_2 & b_3 \\ p & \tilde{b}_1 & \tilde{b}_2 & \tilde{b}_3 \end{array}\end{split}$

where the method and embedding share stage $$A$$ and abscissa $$c$$ values, but use their stages $$z_i$$ differently through the coefficients $$b$$ and $$\tilde{b}$$ to generate methods of orders $$q$$ (the main method) and $$p$$ (the embedding, typically $$q = p+1$$, though sometimes this is reversed). ARKodeButcherTable is defined as

typedef ARKodeButcherTableMem* ARKodeButcherTable

where ARKodeButcherTableMem is the structure

typedef struct ARKodeButcherTableMem {

int q;
int p;
int stages;
realtype **A;
realtype *c;
realtype *b;
realtype *d;

};


where stages is the number of stages in the RK method, the variables q, p, A, c, and b have the same meaning as in the Butcher table above, and d is used to store $$\tilde{b}$$.

ARKodeButcherTable functions¶

Function name Description
ARKodeButcherTable_LoadERK() Retrieve a given explicit Butcher table by its unique name
ARKodeButcherTable_LoadDIRK() Retrieve a given implicit Butcher table by its unique name
ARKodeButcherTable_Alloc() Allocate an empty Butcher table
ARKodeButcherTable_Create() Create a new Butcher table
ARKodeButcherTable_Copy() Create a copy of a Butcher table
ARKodeButcherTable_Space() Get the Butcher table real and integer workspace size
ARKodeButcherTable_Free() Deallocate a Butcher table
ARKodeButcherTable_Write() Write the Butcher table to an output file
ARKodeButcherTable_CheckOrder() Check the order of a Butcher table
ARKodeButcherTable_CheckARKOrder() Check the order of an ARK pair of Butcher tables
ARKodeButcherTable ARKodeButcherTable_LoadERK(int emethod)

Retrieves a specified explicit Butcher table. The prototype for this function, as well as the integer names for each provided method, are defined in the header file arkode/arkode_butcher_erk.h. For further information on these tables and their corresponding identifiers, see Appendix: Butcher tables.

Arguments:
• emethod – integer input specifying the given Butcher table.
Return value:
ARKodeButcherTable ARKodeButcherTable_LoadDIRK(int imethod)

Retrieves a specified diagonally-implicit Butcher table. The prototype for this function, as well as the integer names for each provided method, are defined in the header file arkode/arkode_butcher_dirk.h. For further information on these tables and their corresponding identifiers, see Appendix: Butcher tables.

Arguments:
• imethod – integer input specifying the given Butcher table.
Return value:
ARKodeButcherTable ARKodeButcherTable_Alloc(int stages, booleantype embedded)

Allocates an empty Butcher table.

Arguments:
• stages – the number of stages in the Butcher table.
• embedded – flag denoting whether the Butcher table has an embedding (SUNTRUE) or not (SUNFALSE).
Return value:
ARKodeButcherTable ARKodeButcherTable_Create(int s, int q, int p, realtype *c, realtype *A, realtype *b, realtype *d)

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

Arguments:
• s – number of stages in the RK method.
• q – global order of accuracy for the RK method.
• p – global order of accuracy for the embedded RK method.
• c – array (of length s) of stage times for the RK method.
• A – array of coefficients defining the RK stages. This should be stored as a 1D array of size s*s, in row-major order.
• b – array of coefficients (of length s) defining the time step solution.
• d – array of coefficients (of length s) defining the embedded solution.
Return value:

Notes: If the method does not have an embedding then d should be NULL and p should be equal to zero.

ARKodeButcherTable ARKodeButcherTable_Copy(ARKodeButcherTable B)

Creates copy of the given Butcher table.

Arguments:
• B – the Butcher table to copy.
Return value:
void ARKodeButcherTable_Space(ARKodeButcherTable B, sunindextype *liw, sunindextype *lrw)

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

Arguments:
• B – the Butcher table.
• lenrw – the number of realtype values in the Butcher table workspace.
• leniw – the number of integer values in the Butcher table workspace.
Return value:
• ARK_SUCCESS if successful.
• ARK_MEM_NULL if the Butcher table memory was NULL.
void ARKodeButcherTable_Free(ARKodeButcherTable B)

Deallocate the Butcher table memory.

Arguments:
• B – the Butcher table.
void ARKodeButcherTable_Write(ARKodeButcherTable B, FILE *outfile)

Write the Butcher table to the provided file pointer.

Arguments:
• B – the Butcher table.
• outfile – pointer to use for printing the Butcher table.

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

int ARKodeButcherTable_CheckOrder(ARKodeButcherTable B, int* q, int* p, FILE* outfile)

Determine the analytic order of accuracy for the specified Butcher table. The analytic (necessary) conditions are checked up to order 6. For orders greater than 6 the Butcher simplifying (sufficient) assumptions are used.

Arguments:
• B – the Butcher table.
• q – the measured order of accuracy for the method.
• p – the measured order of accuracy for the embedding; 0 if the method does not have an embedding.
• outfile – file pointer for printing results; NULL to suppress output.
Return value:
• 0 – success, the measured vales of q and p match the values of q and p in the provided Butcher tables.
• 1 – warning, the values of q and p in the provided Butcher tables are lower than the measured values, or the measured values achieve the maximum order possible with this function and the values of q and p in the provided Butcher tables table are higher.
• -1 – failure, the values of q and p in the provided Butcher tables are higher than the measured values.
• -2 – failure, the input Butcher table or critical table contents are NULL.

Notes: For embedded methods, if the return flags for q and p would differ, failure takes precedence over warning, which takes precedence over success.

int ARKodeButcherTable_CheckARKOrder(ARKodeButcherTable B1, ARKodeButcherTable B2, int *q, int *p, FILE *outfile)

Determine the analytic order of accuracy (up to order 6) for a specified ARK pair of Butcher tables.

Arguments:
• B1 – a Butcher table in the ARK pair.
• B2 – a Butcher table in the ARK pair.
• q – the measured order of accuracy for the method.
• p – the measured order of accuracy for the embedding; 0 if the method does not have an embedding.
• outfile – file pointer for printing results; NULL to suppress output.
Return value:
• 0 – success, the measured vales of q and p match the values of q and p in the provided Butcher tables.
• 1 – warning, the values of q and p in the provided Butcher tables are lower than the measured values, or the measured values achieve the maximum order possible with this function and the values of q and p in the provided Butcher tables table are higher.
• -1 – failure, the input Butcher tables or critical table contents are NULL.

Notes: For embedded methods, if the return flags for q and p would differ, warning takes precedence over success.