3.5. Butcher Table Data Structure

To store the Butcher table defining a Runge–Kutta method ARKODE provides the ARKodeButcherTable type and several related utility 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} \quad = \quad \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;
  sunrealtype **A;
  sunrealtype *c;
  sunrealtype *b;
  sunrealtype *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}\).

3.5.1. ARKodeButcherTable functions

Table 3.26 ARKodeButcherTable functions

Function name

Description

ARKodeButcherTable_LoadERK()

Retrieve a given explicit Butcher table by its unique ID

ARKodeButcherTable_LoadERKByName()

Retrieve a given explicit Butcher table by its unique name

ARKodeButcherTable_LoadDIRK()

Retrieve a given implicit Butcher table by its unique ID

ARKodeButcherTable_LoadDIRKByName()

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_IsStifflyAccurate()

Determine if A[stages - 1][i] == b[i]

ARKodeButcherTable_CheckOrder()

Check the order of a Butcher table

ARKodeButcherTable_CheckARKOrder()

Check the order of an ARK pair of Butcher tables

ARKodeButcherTable ARKodeButcherTable_LoadERK(ARKODE_ERKTableID 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 §3.8.

Arguments:
  • emethod – integer input specifying the given Butcher table.

Return value:
ARKodeButcherTable ARKodeButcherTable_LoadERKByName(const char *emethod)

Retrieves a specified explicit Butcher table. The prototype for this function, as well as the 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 names, see §3.8.

Arguments:
  • emethod – name of the Butcher table.

Return value:
  • ARKodeButcherTable structure if successful.

  • NULL pointer if emethod was invalid or "ARKODE_ERK_NONE".

Notes:

This function is case sensitive.

ARKodeButcherTable ARKodeButcherTable_LoadDIRK(ARKODE_DIRKTableID 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 §3.8.

Arguments:
  • imethod – integer input specifying the given Butcher table.

Return value:
ARKodeButcherTable ARKodeButcherTable_LoadDIRKByName(const char *imethod)

Retrieves a specified diagonally-implicit Butcher table. The prototype for this function, as well as the 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 names, see §3.8.

Arguments:
  • imethod – name of the Butcher table.

Return value:
  • ARKodeButcherTable structure if successful.

  • NULL pointer if imethod was invalid or "ARKODE_DIRK_NONE".

Notes:

This function is case sensitive.

ARKodeButcherTable ARKodeButcherTable_Alloc(int stages, sunbooleantype 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 occurred.

ARKodeButcherTable ARKodeButcherTable_Create(int s, int q, int p, sunrealtype *c, sunrealtype *A, sunrealtype *b, sunrealtype *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 occurred.

Notes:

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

Warning

When calling this function from Fortran, it is important to note that A is expected to be in row-major ordering.

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 sunrealtype 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.

void ARKodeButcherTable_IsStifflyAccurate(ARKodeButcherTable B)

Determine if the table satisfies A[stages - 1][i] == b[i]

Arguments:
  • B – the Butcher table.

Returns
  • SUNTRUE if the method is “stiffly accurate”, otherwise returns SUNFALSE

New in version v5.7.0.

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.