2.4.12.2. SplittingStep User-callable functions

This section describes the SplittingStep-specific functions that may be called by the user to setup and then solve an IVP using the SplittingStep time-stepping module.

As discussed in the main ARKODE user-callable function introduction, each of ARKODE’s time-stepping modules clarifies the categories of user-callable functions that it supports. SplittingStep does not support any of the categories beyond the functions that apply for all time-stepping modules.

2.4.12.2.1. SplittingStep initialization functions

void *SplittingStepCreate(SUNStepper *steppers, int partitions, sunrealtype t0, N_Vector y0, SUNContext sunctx)

This function allocates and initializes memory for a problem to be solved using the SplittingStep time-stepping module in ARKODE.

Parameters:

steppers – an array of SUNStepper objects with one for each partition of the IVP. At minimum, they must implement the SUNStepper_Evolve(), SUNStepper_Reset(), SUNStepper_SetStopTime(), and SUNStepper_SetStepDirection() operations.
partitions – the number of partitions, \(P > 1\), in the IVP.
t0 – the initial value of \(t\).
y0 – the initial condition vector \(y(t_0)\).
sunctx – the SUNContext object (see §1.3)

Returns:

If successful, a pointer to initialized problem memory of type void*, to be passed to all user-facing SplittingStep routines listed below. If unsuccessful, a NULL pointer will be returned, and an error message will be printed to stderr.

Example usage:

/* ARKODE objects for integrating individual partitions */
void *partition_mem[] = {NULL, NULL};

/* SUNSteppers to wrap the ARKODE objects */
SUNStepper steppers[] = {NULL, NULL};

/* create ARKODE objects, setting right-hand side functions and the
   initial condition */
partition_mem[0] = ERKStepCreate(f1, t0, y0, sunctx);
partition_mem[1] = ARKStepCreate(fe2, fi2, t0, y0, sunctx);

/* setup ARKODE objects */
. . .

/* create SUNStepper wrappers for the ARKODE memory blocks */
flag = ARKodeCreateSUNStepper(partition_mem[0], &stepper[0]);
flag = ARKodeCreateSUNStepper(partition_mem[1], &stepper[1]);

/* create a SplittingStep object with two partitions */
arkode_mem = SplittingStepCreate(steppers, 2, t0, y0, sunctx);

Example codes:

examples/arkode/C_serial/ark_advection_diffusion_reaction_splitting.c
examples/arkode/C_serial/ark_analytic_partitioned.c

Added in version 6.2.0.

2.4.12.2.2. Optional inputs for IVP method selection

int SplittingStepSetCoefficients(void *arkode_mem, SplittingStepCoefficients coefficients)

Specifies a set of coefficients for the operator splitting method.

Parameters:

arkode_mem – pointer to the SplittingStep memory block.
coefficients – the splitting coefficients for the method.

Return values:

ARK_SUCCESS – if successful
ARK_MEM_NULL – if the SplittingStep memory is NULL
ARK_ILL_INPUT – if an argument has an illegal value

Note

For a description of the SplittingStepCoefficients type and related functions for creating splitting coefficients see §2.4.12.3.

Warning

This should not be used with ARKodeSetOrder().

Added in version 6.2.0.

2.4.12.2.3. Optional output functions

int SplittingStepGetNumEvolves(void *arkode_mem, int partition, long int *evolves)

Returns the number of times the SUNStepper for the given partition index has been evolved (so far).

Parameters:

arkode_mem – pointer to the SplittingStep memory block.
partition – index of the partition between 0 and \(P - 1\) or a negative number to indicate the total number across all partitions.
evolves – number of SUNStepper evolves.

Return values:

ARK_SUCCESS – if successful
ARK_MEM_NULL – if the SplittingStep memory was NULL
ARK_ILL_INPUT – if partition was out of bounds

Added in version 6.2.0.

2.4.12.2.4. SplittingStep re-initialization function

To reinitialize the SplittingStep module for the solution of a new problem, where a prior call to SplittingStepCreate() has been made, the user must call the function SplittingStepReInit() and re-initialize each SUNStepper. The new problem must have the same size as the previous one. This routine retains the current settings for all SplittingStep module options and performs the same input checking and initializations that are done in SplittingStepCreate(), but it performs no memory allocation as it assumes that the existing internal memory is sufficient for the new problem. A call to this re-initialization routine deletes the solution history that was stored internally during the previous integration, and deletes any previously-set tstop value specified via a call to ARKodeSetStopTime(). Following a successful call to SplittingStepReInit(), call ARKodeEvolve() again for the solution of the new problem.

One important use of the SplittingStepReInit() function is in the treating of jump discontinuities in the RHS function. Except in cases of fairly small jumps, it is usually more efficient to stop at each point of discontinuity and restart the integrator with a readjusted ODE model, using a call to this routine. To stop when the location of the discontinuity is known, simply make that location a value of tout. To stop when the location of the discontinuity is determined by the solution, use the rootfinding feature. In either case, it is critical that the RHS function not incorporate the discontinuity, but rather have a smooth extension over the discontinuity, so that the step across it (and subsequent rootfinding, if used) can be done efficiently. Then use a switch within the RHS function (communicated through user_data) that can be flipped between the stopping of the integration and the restart, so that the restarted problem uses the new values (which have jumped). Similar comments apply if there is to be a jump in the dependent variable vector.

Another use of SplittingStepReInit() is changing the partitioning of the ODE and the SUNStepper objects used to evolve each partition.

int SplittingStepReInit(void *arkode_mem, SUNStepper *steppers, int partitions, sunrealtype t0, N_Vector y0)

Provides required problem specifications and re-initializes the SplittingStep time-stepper module.

Parameters:

arkode_mem – pointer to the SplittingStep memory block.
steppers – an array of SUNStepper objects with one for each partition of the IVP. At minimum, they must implement the SUNStepper_Evolve(), SUNStepper_Reset(), SUNStepper_SetStopTime(), and SUNStepper_SetStepDirection() operations.
partitions – the number of partitions, \(P > 1\), in the IVP.
t0 – the initial value of \(t\).
y0 – the initial condition vector \(y(t_0)\).

Return values:

ARK_SUCCESS – if successful
ARK_MEM_NULL – if the SplittingStep memory was NULL
ARK_MEM_FAIL – if a memory allocation failed
ARK_ILL_INPUT – if an argument has an illegal value

Warning

This function does not perform any re-initialization of the SUNStepper objects. It is up to the user to do this, if necessary.

Warning

If the number of partitions changes and coefficients were previously specified with SplittingStepSetCoefficients(), the coefficients will be reset since they are no longer compatible. Otherwise, all previously set options are retained but may be updated by calling the appropriate “Set” functions.

Added in version 6.2.0.