2.4.4.2. SPRKStep User-callable functions

This section describes the functions that are called by the user to setup and then solve an IVP using the SPRKStep time-stepping module. Some of these are required; however, starting with §2.4.4.2.4, the functions listed involve optional inputs/outputs or restarting, and those paragraphs may be skipped for a casual use of ARKODE’s SPRKStep module. In any case, refer to the preceding section, §2.4.4.1, for the correct order of these calls.

On an error, each user-callable function returns a negative value (or NULL if the function returns a pointer) and sends an error message to the error handler routine, which prints the message to stderr by default. However, the user can set a file as error output or can provide their own error handler function (see §2.4.4.2.4 for details).

2.4.4.2.1. SPRKStep initialization and deallocation functions

void *SPRKStepCreate(ARKRhsFn f1, ARKRhsFn f2, sunrealtype t0, N_Vector y0, SUNContext sunctx)

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

Parameters:

f1 – the name of the C function (of type ARKRhsFn()) defining \(f_1(t,q) = \frac{\partial V(t,q)}{\partial q}\)
f2 – the name of the C function (of type ARKRhsFn()) defining \(f_2(t,p) = \frac{\partial T(t,p)}{\partial p}\)
t0 – the initial value of \(t\)
y0 – the initial condition vector \(y(t_0)\)
sunctx – the SUNContext object (see §1.4)

Returns:

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

Warning

SPRKStep requires a partitioned problem where f1 should only modify the q variables and f2 should only modify the p variables (or vice versa). However, the vector passed to these functions is the full vector with both p and q. The ordering of the variables is determined implicitly by the user when they set the initial conditions.

void SPRKStepFree(void **arkode_mem)

This function frees the problem memory arkode_mem created by SPRKStepCreate().

Parameters:

arkode_mem – pointer to the SPRKStep memory block.

2.4.4.2.2. Rootfinding initialization function

As described in §2.2.12, while solving the IVP, ARKODE’s time-stepping modules have the capability to find the roots of a set of user-defined functions. To activate the root-finding algorithm, call the following function. This is normally called only once, prior to the first call to SPRKStepEvolve(), but if the rootfinding problem is to be changed during the solution, SPRKStepRootInit() can also be called prior to a continuation call to SPRKStepEvolve().

Note

The solution is interpolated to the times at which roots are found.

int SPRKStepRootInit(void *arkode_mem, int nrtfn, ARKRootFn g)

Initializes a rootfinding problem to be solved during the integration of the ODE system. It must be called after SPRKStepCreate(), and before SPRKStepEvolve().

To disable the rootfinding feature after it has already been initialized, or to free memory associated with SPRKStep’s rootfinding module, call SPRKStepRootInit() with nrtfn = 0.

Similarly, if a new IVP is to be solved with a call to SPRKStepReInit(), where the new IVP has no rootfinding problem but the prior one did, then call SPRKStepRootInit() with nrtfn = 0.

Parameters:

arkode_mem – pointer to the SPRKStep memory block.
nrtfn – number of functions \(g_i\), an integer \(\ge\) 0.
g – name of user-supplied function, of type ARKRootFn(), defining the functions \(g_i\) whose roots are sought.

Return values:

ARK_SUCCESS – if successful
ARK_MEM_NULL – if the SPRKStep memory was NULL
ARK_MEM_FAIL – if there was a memory allocation failure
ARK_ILL_INPUT – if nrtfn is greater than zero but g = NULL.

2.4.4.2.3. SPRKStep solver function

This is the central step in the solution process – the call to perform the integration of the IVP. One of the input arguments (itask) specifies one of two modes as to where SPRKStep is to return a solution. These modes are modified if the user has set a stop time (with a call to the optional input function SPRKStepSetStopTime()) or has requested rootfinding.

int SPRKStepEvolve(void *arkode_mem, sunrealtype tout, N_Vector yout, sunrealtype *tret, int itask)

Integrates the ODE over an interval in \(t\).

Parameters:

arkode_mem – pointer to the SPRKStep memory block.
tout – the next time at which a computed solution is desired.
yout – the computed solution vector.
tret – the time corresponding to yout (output).
itask –
a flag indicating the job of the solver for the next user step.

The ARK_NORMAL option causes the solver to take internal steps until it has just overtaken a user-specified output time, tout, in the direction of integration, i.e. \(t_{n-1} <\) tout \(\le t_{n}\) for forward integration, or \(t_{n} \le\) tout \(< t_{n-1}\) for backward integration. It will then compute an approximation to the solution \(y(tout)\) by interpolation (using one of the dense output routines described in §2.2.2).

The ARK_ONE_STEP option tells the solver to only take a single internal step, \(y_{n-1} \to y_{n}\), and return the solution at that point, \(y_{n}\), in the vector yout.

Return values:

ARK_SUCCESS – if successful.
ARK_ROOT_RETURN – if SPRKStepEvolve() succeeded, and found one or more roots. If the number of root functions, nrtfn, is greater than 1, call SPRKStepGetRootInfo() to see which \(g_i\) were found to have a root at (*tret).
ARK_TSTOP_RETURN – if SPRKStepEvolve() succeeded and returned at tstop.
ARK_MEM_NULL – if the arkode_mem argument was NULL.
ARK_NO_MALLOC – if arkode_mem was not allocated.
ARK_ILL_INPUT – if one of the inputs to SPRKStepEvolve() is illegal, or some other input to the solver was either illegal or missing. Details will be provided in the error message. Typical causes of this failure are a root of one of the root functions was found both at a point \(t\) and also very near \(t\).
ARK_TOO_MUCH_WORK – if the solver took mxstep internal steps but could not reach tout. The default value for mxstep is MXSTEP_DEFAULT = 500.
ARK_ERR_FAILURE – if error test failures occurred either too many times (ark_maxnef) during one internal time step or occurred with \(|h| = h_{min}\).
ARK_VECTOROP_ERR – a vector operation error occurred.

Note

The input vector yout can use the same memory as the vector y0 of initial conditions that was passed to SPRKStepCreate().

In ARK_ONE_STEP mode, tout is used only on the first call, and only to get the direction and a rough scale of the independent variable.

All failure return values are negative and so testing the return argument for negative values will trap all SPRKStepEvolve() failures.

Since interpolation may reduce the accuracy in the reported solution, if full method accuracy is desired the user should issue a call to SPRKStepSetStopTime() before the call to SPRKStepEvolve() to specify a fixed stop time to end the time step and return to the user. Upon return from SPRKStepEvolve(), a copy of the internal solution \(y_{n}\) will be returned in the vector yout. Once the integrator returns at a tstop time, any future testing for tstop is disabled (and can be re-enabled only though a new call to SPRKStepSetStopTime()). Interpolated outputs may or may not conserve the Hamiltonian. Our testing has shown that Lagrange interpolation typically performs well in this regard, while Hermite interpolation does not. As such, SPRKStep uses the Lagrange interpolation module by default.

On any error return in which one or more internal steps were taken by SPRKStepEvolve(), the returned values of tret and yout correspond to the farthest point reached in the integration. On all other error returns, tret and yout are left unchanged from those provided to the routine.

2.4.4.2.4. Optional input functions

There are numerous optional input parameters that control the behavior of SPRKStep, each of which may be modified from its default value through calling an appropriate input function. The following tables list all optional input functions, grouped by which aspect of SPRKStep they control. Detailed information on the calling syntax and arguments for each function are then provided following each table.

The optional inputs are grouped into the following categories:

General SPRKStep options (Table 2.10),
IVP method solver options (Table 2.11),
Rootfinding options (Table 2.12).

For the most casual use of SPRKStep, relying on the default set of solver parameters, the reader can skip to section on user-supplied functions, §2.4.6.

We note that, on an error return, all of the optional input functions send an error message to the error handler function. All error return values are negative, so a test on the return arguments for negative values will catch all errors. Finally, a call to a SPRKStepSet*** function can generally be made from the user’s calling program at any time and, if successful, takes effect immediately. For SPRKStepSet*** functions that cannot be called at any time, this is explicitly noted in the function documentation.

2.4.4.2.4.1. Optional inputs for SPRKStep

Table 2.10 Optional inputs for SPRKStep
Optional input	Function name	Default
Return SPRKStep solver parameters to their defaults	`SPRKStepSetDefaults()`	internal
Set dense output interpolation type	`SPRKStepSetInterpolantType()`	`ARK_INTERP_LAGRANGE`
Set dense output polynomial degree	`SPRKStepSetInterpolantDegree()`	5
Set fixed step size (required user input)	`SPRKStepSetFixedStep()`	user defined
Maximum no. of internal steps before tout	`SPRKStepSetMaxNumSteps()`	500
Set a value for \(t_{stop}\)	`SPRKStepSetStopTime()`	undefined
Disable the stop time	`SPRKStepClearStopTime()`	N/A
Supply a pointer for user data	`SPRKStepSetUserData()`	`NULL`

int SPRKStepSetDefaults(void *arkode_mem)

Resets all optional input parameters to SPRKStep’s original default values.

Parameters:

arkode_mem – pointer to the SPRKStep memory block.

Return values:

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

Note

Does not change problem-defining function pointer f or the user_data pointer.

Also leaves alone any data structures or options related to root-finding (those can be reset using SPRKStepRootInit()).

int SPRKStepSetInterpolantType(void *arkode_mem, int itype)

Specifies use of the Lagrange or Hermite interpolation modules (used for dense output – interpolation of solution output values and implicit method predictors).

Parameters:

arkode_mem – pointer to the SPRKStep memory block.
itype – requested interpolant type (ARK_INTERP_HERMITE or ARK_INTERP_LAGRANGE)

Return values:

ARK_SUCCESS – if successful
ARK_MEM_NULL – if the SPRKStep memory is NULL
ARK_MEM_FAIL – if the interpolation module cannot be allocated
ARK_ILL_INPUT – if the itype argument is not recognized or the interpolation module has already been initialized

Note

The Hermite interpolation module is described in §2.2.2.1, and the Lagrange interpolation module is described in §2.2.2.2.

This routine frees any previously-allocated interpolation module, and re-creates one according to the specified argument. Thus any previous calls to SPRKStepSetInterpolantDegree() will be nullified.

This routine must be called after the call to SPRKStepCreate(). After the first call to SPRKStepEvolve() the interpolation type may not be changed without first calling SPRKStepReInit().

If this routine is not called, the Lagrange interpolation module will be used.

Interpolated outputs may or may not conserve the Hamiltonian. Our testing has shown that Lagrange interpolation typically performs well in this regard, while Hermite interpolation does not.

int SPRKStepSetInterpolantDegree(void *arkode_mem, int degree)

Specifies the degree of the polynomial interpolant used for dense output (i.e. interpolation of solution output values). Allowed values are between 0 and 5.

Parameters:

arkode_mem – pointer to the SPRKStep memory block.
degree – requested polynomial degree.

Return values:

ARK_SUCCESS – if successful
ARK_MEM_NULL – if the SPRKStep memory or interpolation module are NULL
ARK_INTERP_FAIL – if this is called after SPRKStepEvolve()
ARK_ILL_INPUT – if an argument has an illegal value or the interpolation module has already been initialized

Note

This routine should be called after SPRKStepCreate() and before SPRKStepEvolve(). After the first call to SPRKStepEvolve() the interpolation degree may not be changed without first calling SPRKStepReInit().

If a user calls both this routine and SPRKStepSetInterpolantType(), then SPRKStepSetInterpolantType() must be called first.

Since the accuracy of any polynomial interpolant is limited by the accuracy of the time-step solutions on which it is based, the actual polynomial degree that is used by SPRKStep will be the minimum of \(q-1\) and the input degree, for \(q > 1\) where \(q\) is the order of accuracy for the time integration method.

When q = 1, a linear interpolant is the default to ensure values obtained by the integrator are returned at the ends of the time interval.

int SPRKStepSetFixedStep(void *arkode_mem, sunrealtype hfixed)

Sets the time step size used within SPRKStep.

Parameters:

arkode_mem – pointer to the SPRKStep memory block.
hfixed – value of the fixed step size to use.

Return values:

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

int SPRKStepSetMaxNumSteps(void *arkode_mem, long int mxsteps)

Specifies the maximum number of steps to be taken by the solver in its attempt to reach the next output time, before SPRKStep will return with an error.

Passing mxsteps = 0 results in SPRKStep using the default value (500).

Passing mxsteps < 0 disables the test (not recommended).

Parameters:

arkode_mem – pointer to the SPRKStep memory block.
mxsteps – maximum allowed number of internal steps.

Return values:

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

int SPRKStepSetStopTime(void *arkode_mem, sunrealtype tstop)

Specifies the value of the independent variable \(t\) past which the solution is not to proceed.

The default is that no stop time is imposed.

Once the integrator returns at a stop time, any future testing for tstop is disabled (and can be reenabled only though a new call to SPRKStepSetStopTime()).

A stop time not reached before a call to SPRKStepReInit() or SPRKStepReset() will remain active but can be disabled by calling SPRKStepClearStopTime().

Parameters:

arkode_mem – pointer to the SPRKStep memory block.
tstop – stopping time for the integrator.

Return values:

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

int SPRKStepClearStopTime(void *arkode_mem)

Disables the stop time set with SPRKStepSetStopTime().

The stop time can be reenabled though a new call to SPRKStepSetStopTime().

Parameters:

arkode_mem – pointer to the SPRKStep memory block.

Return values:

ARK_SUCCESS – if successful
ARK_MEM_NULL – if the SPRKStep memory is NULL

int SPRKStepSetUserData(void *arkode_mem, void *user_data)

Specifies the user data block user_data and attaches it to the main SPRKStep memory block.

If specified, the pointer to user_data is passed to all user-supplied functions for which it is an argument; otherwise NULL is passed.

Parameters:

arkode_mem – pointer to the SPRKStep memory block.
user_data – pointer to the user data.

Return values:

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

2.4.4.2.4.2. Optional inputs for IVP method selection

Table 2.11 Optional inputs for IVP method selection
Optional input	Function name	Default
Set integrator method order	`SPRKStepSetOrder()`	4
Set SPRK method	`SPRKStepSetMethod()`	`ARKODE_SPRK_MCLACHLAN_4_4`
Set SPRK method by name	`SPRKStepSetMethodName()`	“ARKODE_SPRK_MCLACHLAN_4_4”
Use compensated summation	`SPRKStepSetUseCompensatedSums()`	false

int SPRKStepSetOrder(void *arkode_mem, int ord)

Specifies the order of accuracy for the SPRK integration method.

The allowed values are \(1,2,3,4,5,6,8,10\). Any illegal input will result in the default value of 4.

Since ord affects the memory requirements for the internal SPRKStep memory block, it cannot be changed after the first call to SPRKStepEvolve(), unless SPRKStepReInit() is called.

Parameters:

arkode_mem – pointer to the SPRKStep memory block.
ord – requested order of accuracy.

Return values:

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

Warning

This overrides any previously set method so it should not be used with SPRKStepSetMethod() or SPRKStepSetMethodName().

int SPRKStepSetMethod(void *arkode_mem, ARKodeSPRKTable sprk_table)

Specifies the SPRK method.

Parameters:

arkode_mem – pointer to the SPRKStep memory block.
sprk_table – the SPRK method table.

Return values:

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

Note

No error checking is performed on the coefficients contained in the table to ensure its declared order of accuracy.

int SPRKStepSetMethodName(void *arkode_mem, const char *method)

Specifies the SPRK method by its name.

Parameters:

arkode_mem – pointer to the SPRKStep memory block.
method – the SPRK method name.

Return values:

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

int SPRKStepSetUseCompensatedSums(void *arkode_mem, sunbooleantype onoff)

Specifies if compensated summation (and the incremental form) should be used where applicable.

This increases the computational cost by 2 extra vector operations per stage and an additional 5 per time step. It also requires one extra vector to be stored. However, it is signficantly more robust to roundoff error accumulation.

Parameters:

arkode_mem – pointer to the SPRKStep memory block.
onoff – should compensated summation be used (1) or not (0)

Return values:

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

2.4.4.2.4.3. Rootfinding optional input functions

The following functions can be called to set optional inputs to control the rootfinding algorithm, the mathematics of which are described in §2.2.12.

Table 2.12 Rootfinding optional input functions
Optional input	Function name	Default
Direction of zero-crossings to monitor	`SPRKStepSetRootDirection()`	both
Disable inactive root warnings	`SPRKStepSetNoInactiveRootWarn()`	enabled

int SPRKStepSetRootDirection(void *arkode_mem, int *rootdir)

Specifies the direction of zero-crossings to be located and returned.

The default behavior is to monitor for both zero-crossing directions.

Parameters:

arkode_mem – pointer to the SPRKStep memory block.
rootdir – state array of length nrtfn, the number of root functions \(g_i\) (the value of nrtfn was supplied in the call to SPRKStepRootInit()). If rootdir[i] == 0 then crossing in either direction for \(g_i\) should be reported. A value of +1 or -1 indicates that the solver should report only zero-crossings where \(g_i\) is increasing or decreasing, respectively.

Return values:

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

int SPRKStepSetNoInactiveRootWarn(void *arkode_mem)

Disables issuing a warning if some root function appears to be identically zero at the beginning of the integration.

SPRKStep will not report the initial conditions as a possible zero-crossing (assuming that one or more components \(g_i\) are zero at the initial time). However, if it appears that some \(g_i\) is identically zero at the initial time (i.e., \(g_i\) is zero at the initial time and after the first step), SPRKStep will issue a warning which can be disabled with this optional input function.

Parameters:

arkode_mem – pointer to the SPRKStep memory block.

Return values:

ARK_SUCCESS – if successful
ARK_MEM_NULL – if the SPRKStep memory is NULL

2.4.4.2.5. Interpolated output function

An optional function SPRKStepGetDky() is available to obtain additional values of solution-related quantities. This function should only be called after a successful return from SPRKStepEvolve(), as it provides interpolated values either of \(y\) or of its derivatives. interpolated to any value of \(t\) in the last internal step taken by SPRKStepEvolve().

int SPRKStepGetDky(void *arkode_mem, sunrealtype t, int k, N_Vector dky)

Computes the k-th derivative of the function \(y\) at the time t, i.e., \(y^{(k)}(t)\), for values of the independent variable satisfying \(t_n-h_n \le t \le t_n\), with \(t_n\) as current internal time reached, and \(h_n\) is the last internal step size successfully used by the solver. A user may access the values \(t_n\) and \(h_n\) via the functions SPRKStepGetCurrentTime() and SPRKStepGetLastStep(), respectively.

This routine uses an interpolating polynomial of degree min(degree, 5), where degree is the argument provided to SPRKStepSetInterpolantDegree(). The user may request k in the range {0,…, min(degree, kmax)} where kmax depends on the choice of interpolation module. For Hermite interpolants kmax = 5 and for Lagrange interpolants kmax = 3.

Parameters:

arkode_mem – pointer to the SPRKStep memory block.
t – the value of the independent variable at which the derivative is to be evaluated.
k – the derivative order requested.
dky – output vector (must be allocated by the user).

Return values:

ARK_SUCCESS – if successful
ARK_BAD_K – if k is not in the range {0,…, min(degree, kmax)}.
ARK_BAD_T – if t is not in the interval \([t_n-h_n, t_n]\)
ARK_BAD_DKY – if the dky vector was NULL
ARK_MEM_NULL – if the SPRKStep memory is NULL

Note

Dense outputs may or may not conserve the Hamiltonian. Our testing has shown that Lagrange interpolation typically performs well in this regard, while Hermite interpolation does not.

Warning

It is only legal to call this function after a successful return from SPRKStepEvolve().

2.4.4.2.6. Optional output functions

SPRKStep provides an extensive set of functions that can be used to obtain solver performance information. We organize these into groups:

General SPRKStep output routines are in §2.4.4.2.6.1,
Output routines regarding root-finding results are in §2.4.4.2.6.2,
General usability routines (e.g. to print the current SPRKStep parameters, or output the current Butcher tables) are in §2.4.4.2.6.3.

Following each table, we elaborate on each function.

Some of the optional outputs, especially the various counters, can be very useful in determining the efficiency of various methods inside SPRKStep. For example:

The counters nsteps and nf_evals provide a rough measure of the overall cost of a given run, and can be compared between runs with different solver options to suggest which set of options is the most efficient.

It is therefore recommended that users retrieve and output these statistics following each run, and take some time to investigate alternate solver options that will be more optimal for their particular problem of interest.

2.4.4.2.6.1. Main solver optional output functions

Table 2.13 Main solver optional output functions
Optional output	Function name
Cumulative number of internal steps	`SPRKStepGetNumSteps()`
Step size used for the last successful step	`SPRKStepGetLastStep()`
Step size to be attempted on the next step	`SPRKStepGetCurrentStep()`
Current internal time reached by the solver	`SPRKStepGetCurrentTime()`
Current internal state reached by the solver	`SPRKStepGetCurrentState()`
Single accessor to many statistics at once	`SPRKStepGetStepStats()`
Print all statistics	`SPRKStepPrintAllStats()`
Name of constant associated with a return flag	`SPRKStepGetReturnFlagName()`
No. of attempted steps	`SPRKStepGetNumStepAttempts()`
No. of calls to right-hand side functions	`SPRKStepGetNumRhsEvals()`
Current method table	`SPRKStepGetCurrentMethod()`
Retrieve a pointer for user data	`SPRKStepGetUserData()`

int SPRKStepGetNumSteps(void *arkode_mem, long int *nsteps)

Returns the cumulative number of internal steps taken by the solver (so far).

Parameters:

arkode_mem – pointer to the SPRKStep memory block.
nsteps – number of steps taken in the solver.

Return values:

ARK_SUCCESS – if successful
ARK_MEM_NULL – if the SPRKStep memory was NULL

int SPRKStepGetLastStep(void *arkode_mem, sunrealtype *hlast)

Returns the integration step size taken on the last successful internal step.

Parameters:

arkode_mem – pointer to the SPRKStep memory block.
hlast – step size taken on the last internal step.

Return values:

ARK_SUCCESS – if successful
ARK_MEM_NULL – if the SPRKStep memory was NULL

int SPRKStepGetCurrentStep(void *arkode_mem, sunrealtype *hcur)

Returns the integration step size to be attempted on the next internal step.

Parameters:

arkode_mem – pointer to the SPRKStep memory block.
hcur – step size to be attempted on the next internal step.

Return values:

ARK_SUCCESS – if successful
ARK_MEM_NULL – if the SPRKStep memory was NULL

int SPRKStepGetCurrentTime(void *arkode_mem, sunrealtype *tcur)

Returns the current internal time reached by the solver.

Parameters:

arkode_mem – pointer to the SPRKStep memory block.
tcur – current internal time reached.

Return values:

ARK_SUCCESS – if successful
ARK_MEM_NULL – if the SPRKStep memory was NULL

int SPRKStepGetCurrentState(void *arkode_mem, N_Vector *ycur)

Returns the current internal solution reached by the solver.

Parameters:

arkode_mem – pointer to the SPRKStep memory block.
ycur – current internal solution

Return values:

ARK_SUCCESS – if successful
ARK_MEM_NULL – if the SPRKStep memory was NULL

Warning

Users should exercise extreme caution when using this function, as altering values of ycur may lead to undesirable behavior, depending on the particular use case and on when this routine is called.

int SPRKStepGetStepStats(void *arkode_mem, long int *nsteps, sunrealtype *hinused, sunrealtype *hlast, sunrealtype *hcur, sunrealtype *tcur)

Returns many of the most useful optional outputs in a single call.

Parameters:

arkode_mem – pointer to the SPRKStep memory block.
nsteps – number of steps taken in the solver.
hinused – actual value of initial step size.
hlast – step size taken on the last internal step.
hcur – step size to be attempted on the next internal step.
tcur – current internal time reached.

Return values:

ARK_SUCCESS – if successful
ARK_MEM_NULL – if the SPRKStep memory was NULL

int SPRKStepPrintAllStats(void *arkode_mem, FILE *outfile, SUNOutputFormat fmt)

Outputs all of the integrator statistics.

Parameters:

arkode_mem – pointer to the SPRKStep memory block.
outfile – pointer to output file.
fmt –
the output format:
- SUN_OUTPUTFORMAT_TABLE – prints a table of values
- SUN_OUTPUTFORMAT_CSV – prints a comma-separated list of key and value pairs e.g., key1,value1,key2,value2,...

Return values:

ARK_SUCCESS – – if the output was successfully.
ARK_MEM_NULL – – if the SPRKStep memory was NULL.
ARK_ILL_INPUT – – if an invalid formatting option was provided.

Note

The file scripts/sundials_csv.py provides python utility functions to read and output the data from a SUNDIALS CSV output file using the key and value pair format.

char *SPRKStepGetReturnFlagName(long int flag)

Returns the name of the SPRKStep constant corresponding to flag. See ARKODE Constants.

Parameters:

flag – a return flag from an SPRKStep function.

Returns:

The return value is a string containing the name of the corresponding constant.

int SPRKStepGetNumStepAttempts(void *arkode_mem, long int *step_attempts)

Returns the cumulative number of steps attempted by the solver (so far).

Parameters:

arkode_mem – pointer to the SPRKStep memory block.
step_attempts – number of steps attempted by solver.

Return values:

ARK_SUCCESS – if successful
ARK_MEM_NULL – if the SPRKStep memory was NULL

int SPRKStepGetNumRhsEvals(void *arkode_mem, long int *nf1, long int *nf2)

Returns the number of calls to the user’s right-hand side functions, \(f_1\) and \(f_2\) (so far).

Parameters:

arkode_mem – pointer to the SPRKStep memory block.
nf1 – number of calls to the user’s \(f_1(t,p)\) function.
nf2 – number of calls to the user’s \(f_2(t,q)\) function.

Return values:

ARK_SUCCESS – if successful
ARK_MEM_NULL – if the SPRKStep memory was NULL

int SPRKStepGetCurrentMethod(void *arkode_mem, ARKodeSPRKTable *sprk_table)

Returns the SPRK method coefficient table currently in use by the solver.

Parameters:

arkode_mem – pointer to the SPRKStep memory block.
sprk_table – pointer to the SPRK method table.

Return values:

ARK_SUCCESS – if successful
ARK_MEM_NULL – if the SPRKStep memory was NULL

int SPRKStepGetUserData(void *arkode_mem, void **user_data)

Returns the user data pointer previously set with SPRKStepSetUserData().

Parameters:

arkode_mem – pointer to the SPRKStep memory block.
user_data – memory reference to a user data pointer

Return values:

ARK_SUCCESS – if successful
ARK_MEM_NULL – if the ARKStep memory was NULL

2.4.4.2.6.2. Rootfinding optional output functions

Table 2.14 Rootfinding optional output functions
Optional output	Function name
Array showing roots found	`SPRKStepGetRootInfo()`
No. of calls to user root function	`SPRKStepGetNumGEvals()`

int SPRKStepGetRootInfo(void *arkode_mem, int *rootsfound)

Returns an array showing which functions were found to have a root.

For the components of \(g_i\) for which a root was found, the sign of rootsfound[i] indicates the direction of zero-crossing. A value of +1 indicates that \(g_i\) is increasing, while a value of -1 indicates a decreasing \(g_i\).

The user must allocate space for rootsfound prior to calling this function.

Parameters:

arkode_mem – pointer to the SPRKStep memory block.
rootsfound – array of length nrtfn with the indices of the user functions \(g_i\) found to have a root (the value of nrtfn was supplied in the call to SPRKStepRootInit()). For \(i = 0 \ldots\) nrtfn-1, rootsfound[i] is nonzero if \(g_i\) has a root, and 0 if not.

Return values:

ARK_SUCCESS – if successful
ARK_MEM_NULL – if the SPRKStep memory was NULL

int SPRKStepGetNumGEvals(void *arkode_mem, long int *ngevals)

Returns the cumulative number of calls made to the user’s root function \(g\).

Parameters:

arkode_mem – pointer to the SPRKStep memory block.
ngevals – number of calls made to \(g\) so far.

Return values:

ARK_SUCCESS – if successful
ARK_MEM_NULL – if the SPRKStep memory was NULL

2.4.4.2.6.3. General usability functions

The following optional routine may be called by a user to inquire about existing solver parameters. While it would not typically be called during the course of solving an initial value problem, it may be useful for users wishing to better understand SPRKStep.

Table 2.15 General usability functions
Optional routine	Function name
Output all SPRKStep solver parameters	`SPRKStepWriteParameters()`

int SPRKStepWriteParameters(void *arkode_mem, FILE *fp)

Outputs all SPRKStep solver parameters to the provided file pointer.

The fp argument can be stdout or stderr, or it may point to a specific file created using fopen.

When run in parallel, only one process should set a non-NULL value for this pointer, since parameters for all processes would be identical.

Parameters:

arkode_mem – pointer to the SPRKStep memory block.
fp – pointer to use for printing the solver parameters.

Return values:

ARK_SUCCESS – if successful
ARK_MEM_NULL – if the SPRKStep memory was NULL

2.4.4.2.7. SPRKStep re-initialization function

To reinitialize the SPRKStep module for the solution of a new problem, where a prior call to SPRKStepCreate() has been made, the user must call the function SPRKStepReInit(). The new problem must have the same size as the previous one. This routine retains the current settings for all SPRKStep module options and performs the same input checking and initializations that are done in SPRKStepCreate(), 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 SPRKStepSetStopTime(). Following a successful call to SPRKStepReInit(), call SPRKStepEvolve() again for the solution of the new problem.

The use of SPRKStepReInit() requires that the number of Runge–Kutta stages, denoted by s, be no larger for the new problem than for the previous problem. This condition is automatically fulfilled if the method order q is left unchanged.

One potential use of the SPRKStepReInit() function is in the treating of jump discontinuities in the RHS function [121]. In lieu of including if statements within the RHS function to handle discontinuities, it may be more computationally efficient to stop at each point of discontinuity (e.g., through use of tstop or the rootfinding feature) and restart the integrator with a readjusted ODE model, using a call to this routine. We note that for the solution to retain temporal accuracy, the RHS function should not incorporate the discontinuity.

int SPRKStepReInit(void *arkode_mem, ARKRhsFn f1, ARKRhsFn f2, sunrealtype t0, N_Vector y0)

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

All previously set options are retained but may be updated by calling the appropriate “Set” functions.

If an error occurred, SPRKStepReInit() also sends an error message to the error handler function.

Parameters:

arkode_mem – pointer to the SPRKStep memory block.
f1 – the name of the C function (of type ARKRhsFn()) defining \(f1(t,q) = \frac{\partial V(t,q)}{\partial q}\)
f2 – the name of the C function (of type ARKRhsFn()) defining \(f2(t,p) = \frac{\partial T(t,p)}{\partial p}\)
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 SPRKStep memory was NULL
ARK_MEM_FAIL – if a memory allocation failed
ARK_ILL_INPUT – if an argument has an illegal value.

2.4.4.2.8. SPRKStep reset function

To reset the SPRKStep module to a particular state \((t_R,y(t_R))\) for the continued solution of a problem, where a prior call to SPRKStepCreate() has been made, the user must call the function SPRKStepReset(). Like SPRKStepReInit() this routine retains the current settings for all SPRKStep module options and performs no memory allocations but, unlike SPRKStepReInit(), this routine performs only a subset of the input checking and initializations that are done in SPRKStepCreate(). In particular this routine retains all internal counter values. Like SPRKStepReInit(), a call to SPRKStepReset() will delete any previously-set tstop value specified via a call to SPRKStepSetStopTime(). Following a successful call to SPRKStepReset(), call SPRKStepEvolve() again to continue solving the problem. By default the next call to SPRKStepEvolve() will use the step size computed by SPRKStep prior to calling SPRKStepReset().

int SPRKStepReset(void *arkode_mem, sunrealtype tR, N_Vector yR)

Resets the current SPRKStep time-stepper module state to the provided independent variable value and dependent variable vector.

All previously set options are retained but may be updated by calling the appropriate “Set” functions.

If an error occurred, SPRKStepReset() also sends an error message to the error handler function.

Parameters:

arkode_mem – pointer to the SPRKStep memory block.
tR – the value of the independent variable \(t\).
yR – the value of the dependent variable vector \(y(t_R)\).

Return values:

ARK_SUCCESS – if successful
ARK_MEM_NULL – if the SPRKStep memory was NULL
ARK_MEM_FAIL – if a memory allocation failed
ARK_ILL_INPUTL – if an argument has an illegal value.

Note

By default the next call to SPRKStepEvolve() will use the step size computed by SPRKStep prior to calling SPRKStepReset().