3.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 §3.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, §3.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
§3.4.4.2.4 for details).
3.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 §2.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, aNULL
pointer will be returned, and an error message will be printed tostderr
.
Warning
SPRKStep requires a partitioned problem where
f1
should only modify the q variables andf2
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.
3.4.4.2.2. Rootfinding initialization function
As described in §3.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 beforeSPRKStepEvolve()
.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 callSPRKStepRootInit()
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
.
3.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 §3.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, callSPRKStepGetRootInfo()
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 toSPRKStepEvolve()
to specify a fixed stop time to end the time step and return to the user. Upon return fromSPRKStepEvolve()
, 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 toSPRKStepSetStopTime()
). 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.
3.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 3.10),
IVP method solver options (Table 3.11),
Rootfinding options (Table 3.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, §3.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.
3.4.4.2.4.1. Optional inputs for SPRKStep
Optional input |
Function name |
Default |
---|---|---|
Return SPRKStep solver parameters to their defaults |
internal |
|
Set dense output interpolation type |
|
|
Set dense output polynomial degree |
5 |
|
Supply a pointer to a diagnostics output file |
|
|
Set fixed step size (required user input) |
user defined |
|
Maximum no. of internal steps before tout |
500 |
|
Set a value for \(t_{stop}\) |
undefined |
|
Disable the stop time |
N/A |
|
Supply a pointer for user data |
|
-
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
orARK_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 §3.2.2.1, and the Lagrange interpolation module is described in §3.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 toSPRKStepEvolve()
the interpolation type may not be changed without first callingSPRKStepReInit()
.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 beforeSPRKStepEvolve()
. After the first call toSPRKStepEvolve()
the interpolation degree may not be changed without first callingSPRKStepReInit()
.If a user calls both this routine and
SPRKStepSetInterpolantType()
, thenSPRKStepSetInterpolantType()
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 toSPRKStepSetStopTime()
).A stop time not reached before a call to
SPRKStepReInit()
orSPRKStepReset()
will remain active but can be disabled by callingSPRKStepClearStopTime()
.- 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
3.4.4.2.4.2. Optional inputs for IVP method selection
Optional input |
Function name |
Default |
---|---|---|
Set integrator method order |
4 |
|
Set SPRK method |
|
|
Set SPRK method by name |
“ARKODE_SPRK_MCLACHLAN_4_4” |
|
Use compensated summation |
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()
, unlessSPRKStepReInit()
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()
orSPRKStepMethodByName()
.
-
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
3.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 §3.2.12.
Optional input |
Function name |
Default |
---|---|---|
Direction of zero-crossings to monitor |
both |
|
Disable inactive root warnings |
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()
). Ifrootdir[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
3.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()
andSPRKStepGetLastStep()
, 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()
.
3.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 §3.4.4.2.6.1,
Output routines regarding root-finding results are in §3.4.4.2.6.2,
General usability routines (e.g. to print the current SPRKStep parameters, or output the current Butcher tables) are in §3.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.
3.4.4.2.6.1. Main solver optional output functions
Optional output |
Function name |
---|---|
Cumulative number of internal steps |
|
Step size used for the last successful step |
|
Step size to be attempted on the next step |
|
Current internal time reached by the solver |
|
Current internal state reached by the solver |
|
Single accessor to many statistics at once |
|
Print all statistics |
|
Name of constant associated with a return flag |
|
No. of attempted steps |
|
No. of calls to right-hand side functions |
|
Current method table |
|
Retrieve a pointer for user data |
-
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 valuesSUN_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 Appendix: 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
3.4.4.2.6.2. Rootfinding optional output functions
Optional output |
Function name |
---|---|
Array showing roots found |
|
No. of calls to user root function |
-
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
3.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.
Optional routine |
Function name |
Output all SPRKStep solver parameters |
-
int SPRKStepWriteParameters(void *arkode_mem, FILE *fp)
Outputs all SPRKStep solver parameters to the provided file pointer.
The fp argument can be
stdout
orstderr
, or it may point to a specific file created usingfopen
.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
3.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.
3.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 callingSPRKStepReset()
.