# 2.5. Butcher Table Data Structure

To store a Butcher table, $$B$$, defining a Runge–Kutta method ARKODE provides the ARKodeButcherTable type and several related utility routines. We use the following notation

$\begin{split}B \; \equiv \; \begin{array}{r|c} c & A \\ \hline q & b \\ p & \tilde{b} \end{array} \; = \; \begin{array}{c|cccc} c_1 & a_{1,1} & \cdots & a_{1,s-1} & a_{1,s} \\ c_2 & a_{2,1} & \cdots & a_{2,s-1} & a_{2,s} \\ \vdots & \vdots & \vdots & \vdots & \vdots \\ c_s & a_{s,1} & \cdots & a_{s,s-1} & a_{s,s} \\ \hline q & b_1 & \cdots & b_{s-1} & b_s \\ p & \tilde{b}_1 & \cdots & \tilde{b}_{s-1} & \tilde{b}_s \end{array}.\end{split}$

An ARKodeButcherTable is a pointer to the ARKodeButcherTableMem structure:

typedef ARKodeButcherTableMem *ARKodeButcherTable
struct ARKodeButcherTableMem

Structure for storing a Butcher table

int q

The method order of accuracy

int p

The embedding order of accuracy, typically $$q = p + 1$$

int stages

The number of stages in the method, $$s$$

sunrealtype **A

The method coefficients $$A \in \mathbb{R}^s$$

sunrealtype *c

The method abscissa $$c \in \mathbb{R}^s$$

sunrealtype *b

The method coefficients $$b \in \mathbb{R}^s$$

sunrealtype *d

The method embedding coefficients $$\tilde{b} \in \mathbb{R}^s$$

## 2.5.1. 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_ERKIDToName() Convert an explicit Butcher table ID to its 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_DIRKIDToName() Convert an implicit Butcher table ID to its 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

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 §2.8.

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

Return value:

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 §2.8.

Arguments:
• emethod – name of the Butcher table.

Return value:
Notes:

This function is case sensitive.

const char *ARKodeButcherTable_ERKIDToName(ARKODE_ERKTableID emethod)

Converts a specified explicit Butcher table ID to a string of the same name. 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 §2.8.

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

Return value:
• The name associated with emethod.

• NULL pointer if emethod was invalid.

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 §2.8.

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

Return value:

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 §2.8.

Arguments:
• imethod – name of the Butcher table.

Return value:
Notes:

This function is case sensitive.

const char *ARKodeButcherTable_DIRKIDToName(ARKODE_DIRKTableID imethod)

Converts a specified diagonally-implicit Butcher table ID to a string of the same name. 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 §2.8.

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

Return value:
• The name associated with imethod.

• NULL pointer if imethod was invalid.

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 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:
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

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.