2.4.12.3. Operator Splitting Coefficients Data Structure

SplittingStep supplies several functions to construct operator splitting coefficients of various orders and partitions. There are also a number of built-in methods of fixed orders and partitions (see §2.4.12.3.2). Finally, a user may construct a custom set of coefficients and attach it with SplittingStepSetCoefficients(). The operator splitting coefficients are stored in a SplittingStepCoefficients object which is a pointer to a SplittingStepCoefficientsMem structure:

typedef SplittingStepCoefficientsMem *SplittingStepCoefficients

struct SplittingStepCoefficientsMem

Structure for storing the coefficients defining an operator splitting method.

As described in §2.2.8, an operator splitting method is defined by a vector \(\alpha \in \mathbb{R}^{r}\) and a tensor \(\beta \in \mathbb{R}^{r \times (s + 1) \times P}\) where \(r\) is the number of sequential methods, \(s\) is the number of stages, and \(P\) is the number of partitions.

sunrealtype *alpha

An array containing the weight of each sequential method used to produce the overall operator splitting solution. The array is of length [sequential_methods].

sunrealtype ***beta

A three-dimensional array containing the time nodes of the partition integrations. The array has dimensions [sequential_methods][stages+1][partitions].

int sequential_methods

The number of sequential methods, \(r\), combined to produce the overall operator splitting solution

int stages

The number of stages, \(s\)

int partitions

The number of partitions, \(P\), in the IVP

int order

The method order of accuracy

2.4.12.3.1. SplittingStepCoefficients Functions

This section describes the functions for creating and interacting with operator splitting coefficients. The function prototypes and as well as the relevant integer constants are defined arkode/arkode_splittingstep.h.

Table 2.9 SplittingStepCoefficients functions

Function name	Description
SplittingStepCoefficients_LoadCoefficients()	Load a pre-defined SplittingStepCoefficients by ID
SplittingStepCoefficients_LoadCoefficientsByName()	Load a pre-defined SplittingStepCoefficients by name
SplittingStepCoefficients_IDToName()	Convert a pre-defined SplittingStepCoefficients to its name
SplittingStepCoefficients_LieTrotter()	Create a Lie–Trotter splitting method
SplittingStepCoefficients_Strang()	Create a Strang splitting method
SplittingStepCoefficients_SymmetricParallel()	Create a symmetrization of the Lie–Trotter splitting method
SplittingStepCoefficients_ThirdOrderSuzuki()	Create a third order composition method of Suzuki
SplittingStepCoefficients_TripleJump()	Create an arbitrary order, three-jump composition method
SplittingStepCoefficients_SuzukiFractal()	Create an arbitrary order, five-jump composition method
SplittingStepCoefficients_Alloc()	Allocate an empty SplittingStepCoefficients object
SplittingStepCoefficients_Create()	Create a new SplittingStepCoefficients object from coefficient arrays
SplittingStepCoefficients_Copy()	Create a copy of a SplittingStepCoefficients object
SplittingStepCoefficients_Destroy()	Deallocate a SplittingStepCoefficients object
SplittingStepCoefficients_Write()	Write the SplittingStepCoefficients object to an output file

SplittingStepCoefficients SplittingStepCoefficients_LoadCoefficients(ARKODE_SplittingCoefficientsID method)

Retrieves specified splitting coefficients. For further information on the current set of splitting coefficients and their corresponding identifiers, see §2.4.12.3.2.

Parameters:

• method – the splitting coefficients identifier.

Returns:

A SplittingStepCoefficients structure if successful or a NULL pointer if method was invalid or an allocation error occurred.

Added in version 6.2.0.

SplittingStepCoefficients SplittingStepCoefficients_LoadCoefficientsByName(const char *method)

Retrieves specified splitting coefficients. For further information on the current set of splitting coefficients and their corresponding name, see §2.4.12.3.2.

Parameters:

• method – the splitting coefficients identifier.

Returns:

A SplittingStepCoefficients structure if successful or a NULL pointer if method was invalid or an allocation error occurred.

Note

This function is case sensitive.

Added in version 6.2.0.

const char *SplittingStepCoefficients_IDToName(ARKODE_SplittingCoefficientsID method)

Converts specified splitting coefficients ID to a string of the same name. For further information on the current set of splitting coefficients and their corresponding name, see §2.4.12.3.2.

Parameters:

• method – the splitting coefficients identifier.

Returns:

A SplittingStepCoefficients structure if successful or a NULL pointer if method was invalid or an allocation error occurred.

Added in version 6.2.0.

SplittingStepCoefficients SplittingStepCoefficients_LieTrotter(int partitions)

Create the coefficients for the first order Lie–Trotter splitting, see (2.24).

Parameters:

• partitions – The number of partitions, \(P > 1\), in the IVP.

Returns:

A SplittingStepCoefficients structure if successful or a NULL pointer if partitions was invalid or an allocation error occurred.

Added in version 6.2.0.

SplittingStepCoefficients SplittingStepCoefficients_Strang(int partitions)

Create the coefficients for the second order Strang splitting [144], see (2.26).

Parameters:

• partitions – The number of partitions, \(P > 1\), in the IVP.

Returns:

A SplittingStepCoefficients structure if successful or a NULL pointer if partitions was invalid or an allocation error occurred.

Added in version 6.2.0.

SplittingStepCoefficients SplittingStepCoefficients_Parallel(int partitions)

Create the coefficients for the first order parallel splitting method

\[y_n = \phi^1_{h_n}(y_{n-1}) + \phi^2_{h_n}(y_{n-1}) + \dots + \phi^P_{h_n}(y_{n-1}) + (1 - P) y_{n-1}.\]

Parameters:

• partitions – The number of partitions, \(P > 1\), in the IVP.

Returns:

A SplittingStepCoefficients structure if successful or a NULL pointer if partitions was invalid or an allocation error occurred.

Added in version 6.2.0.

SplittingStepCoefficients SplittingStepCoefficients_SymmetricParallel(int partitions)

Create the coefficients for the second order, symmetrized Lie–Trotter splitting [143]

\[y_n = \frac{1}{2} \left( L_{h_n}(y_{n-1}) + L^*_{h_n}(y_{n-1}) \right),\]

where \(L_{h_n}\) is the Lie–Trotter splitting (2.24) and \(L^*_{h_n}\) is its adjoint (2.25).

Parameters:

• partitions – The number of partitions, \(P > 1\), in the IVP.

Returns:

A SplittingStepCoefficients structure if successful or a NULL pointer if partitions was invalid or an allocation error occurred.

Added in version 6.2.0.

SplittingStepCoefficients SplittingStepCoefficients_ThirdOrderSuzuki(int partitions)

Create the coefficients for a splitting method of Suzuki [148]

\[y_n = \left( L_{p_1 h_n} \circ L^*_{p_2 h_n} \circ L_{p_3 h_n} \circ L^*_{p_4 h_n} \circ L_{p_5 h_n} \right) (y_{n-1}),\]

where \(L_{h_n}\) is the Lie–Trotter splitting (2.24) and \(L^*_{h_n}\) is its adjoint (2.25). The parameters \(p_1, \dots, p_5\) are selected to give third order.

Parameters:

• partitions – The number of partitions, \(P > 1\), in the IVP.

Returns:

A SplittingStepCoefficients structure if successful or a NULL pointer if partitions was invalid or an allocation error occurred.

Added in version 6.2.0.

SplittingStepCoefficients SplittingStepCoefficients_TripleJump(int partitions, int order)

Create the coefficients for the triple jump splitting method [43]

\[\begin{split}T_{h_n}^{[2]} &= S_{h_n}, \\ T_{h_n}^{[i+2]} &= T_{\gamma_1 h_n}^{[i]} \circ T_{(1 - 2 \gamma_1) h_n}^{[i]} \circ T_{\gamma_1 h_n}^{[i]}, \\ y_n &= T_{h_n}^{[\mathrm{order}]}(y_{n-1}),\end{split}\]

where \(S\) is the Strang splitting (2.26) and \(\gamma_1\) is selected to increase the order by two each recursion.

Parameters:

• partitions – The number of partitions, \(P > 1\), in the IVP.

• order – A positive even number for the method order of accuracy.

Returns:

A SplittingStepCoefficients structure if successful or a NULL pointer if an argument was invalid or an allocation error occurred.

Added in version 6.2.0.

SplittingStepCoefficients SplittingStepCoefficients_SuzukiFractal(int partitions, int order)

Create the coefficients for the quintuple jump splitting method [147]

\[\begin{split}Q_{h_n}^{[2]} &= S_{h_n}, \\ Q_{h_n}^{[i+2]} &= Q_{\gamma_1 h_n}^{[i]} \circ Q_{\gamma_1 h_n}^{[i]} \circ Q_{(1 - 4 \gamma_1) h_n}^i \circ Q_{\gamma_1 h_n}^{[i]} \circ Q_{\gamma_1 h_n}^{[i]}, \\ y_n &= Q_{h_n}^{[\mathrm{order}]}(y_{n-1}),\end{split}\]

where \(S\) is the Strang splitting (2.26) and \(\gamma_1\) is selected to increase the order by two each recursion.

Parameters:

• partitions – The number of partitions, \(P > 1\), in the IVP.

• order – A positive even number for the method order of accuracy.

Returns:

A SplittingStepCoefficients structure if successful or a NULL pointer if an argument was invalid or an allocation error occurred.

Added in version 6.2.0.

SplittingStepCoefficients SplittingStepCoefficients_Alloc(int sequential_methods, int stages, int partitions)

Allocates an empty SplittingStepCoefficients object.

Parameters:

• sequential_methods – The number of sequential methods, \(r \geq 1\), combined to produce the overall operator splitting solution.

• stages – The number of stages, \(s \geq 1\).

• partitions – The number of partitions, \(P > 1\), in the IVP.

Returns:

A SplittingStepCoefficients structure if successful or a NULL pointer if an argument was invalid or an allocation error occurred.

Added in version 6.2.0.

SplittingStepCoefficients SplittingStepCoefficients_Create(int sequential_methods, int stages, int partitions, int order, sunrealtype *alpha, sunrealtype *beta)

Allocates a SplittingStepCoefficients object and fills it with the given values.

Parameters:

• sequential_methods – The number of sequential methods, \(r \geq 1\) combined to produce the overall operator splitting solution.

• stages – The number of stages, \(s \geq 1\).

• partitions – The number of partitions, \(P > 1\) in the IVP.

• order – The method order of accuracy.

• alpha – An array of length sequential_methods containing the weight of each sequential method used to produce the overall operator splitting solution.

• beta –

  An array of length sequential_methods * (stages+1) * partitions containing the time nodes of the partition integrations in the C order

  \[\begin{split}& \beta_{1,1,1}, \dots, \beta_{1,1,P}, \dots, \beta_{1,s+1,1}, \dots, \beta_{1,s+1,P}, \dots, \\ & \beta_{2,1,1}, \dots, \beta_{2,1,P}, \dots, \beta_{2,s+1,1}, \dots, \beta_{2,s+1,P}, \dots, \\ & \beta_{r,1,1}, \dots, \beta_{r,1,P}, \dots, \beta_{r,s+1,1}, \dots, \beta_{r,s+1,P}.\end{split}\]

Returns:

A SplittingStepCoefficients structure if successful or a NULL pointer if an argument was invalid or an allocation error occurred.

Added in version 6.2.0.

SplittingStepCoefficients SplittingStepCoefficients_Copy(SplittingStepCoefficients coefficients)

Creates copy of the given splitting coefficients.

Parameters:

• coefficients – The splitting coefficients to copy.

Returns:

A SplittingStepCoefficients structure if successful or a NULL pointer if an allocation error occurred.

Added in version 6.2.0.

void SplittingStepCoefficients_Destroy(SplittingStepCoefficients *coefficients)

Deallocate the splitting coefficients memory.

Parameters:

• coefficients – A pointer to the splitting coefficients.

Added in version 6.2.0.

void SplittingStepCoefficients_Write(SplittingStepCoefficients coefficients, FILE *outfile)

Write the splitting coefficients to the provided file pointer.

Parameters:

• coefficients – The splitting coefficients.

• outfile – Pointer to use for printing the splitting coefficients. It can be stdout or stderr, or it may point to a specific file created using fopen.

Added in version 6.2.0.

2.4.12.3.2. Operator Splitting Coefficients

SplittingStep currently provides several pre-defined coefficients for problems with two partitions. We list the identifiers, order of accuracy, and relevant references for each in the table below. We use the naming convention

ARKODE_SPLITTING_<name>_<stages>_<order>_<partitions>

Each of the splitting coefficients that are packaged with SplittingStep are specified by a unique ID having type:

enum ARKODE_SplittingCoefficientsID

with values specified for each method below (e.g., ARKODE_SPLITTING_LIE_TROTTER_1_1_2).

Table 2.10 Operator splitting coefficients.

Table name	Order	Reference
ARKODE_SPLITTING_LIE_TROTTER_1_1_2	1
ARKODE_SPLITTING_STRANG_2_2_2	2	[144]
ARKODE_SPLITTING_BEST_2_2_2	2	[15]
ARKODE_SPLITTING_SUZUKI_3_3_2	3	[148]
ARKODE_SPLITTING_RUTH_3_3_2	3	[120]
ARKODE_SPLITTING_YOSHIDA_4_4_2	4	[159]
ARKODE_SPLITTING_YOSHIDA_8_6_2	6	[159]

2.4.12.3.3. Default Operator Splitting Coefficients

The default SplittingStep coefficients are Lie–Trotter. If a particular order is requested with ARKodeSetOrder(), the following are the default for each order

Table 2.11 Default operator splitting coefficients by order.

Order	Default operator splitting coefficients
1	SplittingStepCoefficients_LieTrotter()
2	SplittingStepCoefficients_Strang()
3	SplittingStepCoefficients_ThirdOrderSuzuki()
4, 6, 8, …	SplittingStepCoefficients_TripleJump()
5, 7, 9, …	Warning: this will select a triple jump method of the next even order