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 structure if successful.
  • NULL pointer if stages was invalid or an allocation error occured.
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:
  • ARKodeButcherTable structure if successful.
  • NULL pointer if stages was invalid or an allocation error occured.

Notes: If the method does not have an embedding then d should be NULL and q 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.