Usercallable functions
This section describes the functions that are called by the user to
setup and then solve an IVP using the ARKStep timestepping
module. Some of these are required; however, starting with the section
Optional input functions, the functions listed involve
optional inputs/outputs or restarting, and those paragraphs may be
skipped for a casual use of ARKode’s ARKStep module. In any case,
refer to the preceding section, A skeleton of the user’s main program,
for the correct order of these calls.
On an error, each usercallable 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 her own error handler function (see the section
Optional input functions for details).
ARKStep initialization and deallocation functions

void*
ARKStepCreate
(ARKRhsFn fe, ARKRhsFn fi, realtype t0, N_Vector y0)
This function creates an internal memory block for a problem to be
solved using the ARKStep timestepping module in ARKode.
 Arguments:
 fe – the name of the C function (of type
ARKRhsFn()
)
defining the explicit portion of the righthand side function in
\(M\, \dot{y} = f_E(t,y) + f_I(t,y)\).
 fi – the name of the C function (of type
ARKRhsFn()
)
defining the implicit portion of the righthand side function in
\(M\, \dot{y} = f_E(t,y) + f_I(t,y)\).
 t0 – the initial value of \(t\).
 y0 – the initial condition vector \(y(t_0)\).
Return value: If successful, a pointer to initialized problem memory
of type void*
, to be passed to all userfacing ARKStep routines
listed below. If unsuccessful, a NULL
pointer will be
returned, and an error message will be printed to stderr
.

void
ARKStepFree
(void** arkode_mem)
This function frees the problem memory arkode_mem created by
ARKStepCreate()
.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
Return value: None
ARKStep tolerance specification functions
These functions specify the integration tolerances. One of them
should be called before the first call to
ARKStepEvolve()
; otherwise default values of reltol =
1e4
and abstol = 1e9
will be used, which may be entirely
incorrect for a specific problem.
The integration tolerances reltol
and abstol
define a vector
of error weights, ewt
. In the case of
ARKStepSStolerances()
, this vector has components
ewt[i] = 1.0/(reltol*abs(y[i]) + abstol);
whereas in the case of ARKStepSVtolerances()
the vector components
are given by
ewt[i] = 1.0/(reltol*abs(y[i]) + abstol[i]);
This vector is used in all error and convergence tests, which use a
weighted RMS norm on all errorlike vectors \(v\):
\[\v\_{WRMS} = \left( \frac{1}{N} \sum_{i=1}^N (v_i\; ewt_i)^2 \right)^{1/2},\]
where \(N\) is the problem dimension.
Alternatively, the user may supply a custom function to supply the
ewt
vector, through a call to ARKStepWFtolerances()
.

int
ARKStepSStolerances
(void* arkode_mem, realtype reltol, realtype abstol)
This function specifies scalar relative and absolute tolerances.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 reltol – scalar relative tolerance.
 abstol – scalar absolute tolerance.
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL
 ARK_NO_MALLOC if the ARKStep memory was not allocated by the timestepping module
 ARK_ILL_INPUT if an argument has an illegal value (e.g. a negative tolerance).

int
ARKStepSVtolerances
(void* arkode_mem, realtype reltol, N_Vector abstol)
This function specifies a scalar relative tolerance and a vector
absolute tolerance (a potentially different absolute tolerance for
each vector component).
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 reltol – scalar relative tolerance.
 abstol – vector containing the absolute tolerances for each
solution component.
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL
 ARK_NO_MALLOC if the ARKStep memory was not allocated by the timestepping module
 ARK_ILL_INPUT if an argument has an illegal value (e.g. a negative tolerance).

int
ARKStepWFtolerances
(void* arkode_mem, ARKEwtFn efun)
This function specifies a usersupplied function efun to compute
the error weight vector ewt
.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 efun – the name of the function (of type
ARKEwtFn()
)
that implements the error weight vector computation.
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL
 ARK_NO_MALLOC if the ARKStep memory was not allocated by the timestepping module
Moreover, for problems involving a nonidentity mass matrix
\(M \ne I\), the units of the solution vector \(y\) may differ
from the units of the IVP, posed for the vector \(My\). When this
occurs, iterative solvers for the Newton linear systems and the mass
matrix linear systems may require a different set of tolerances.
Since the relative tolerance is dimensionless, but the absolute
tolerance encodes a measure of what is “small” in the units of the
respective quantity, a user may optionally define absolute tolerances
in the equation units. In this case, ARKStep defines a vector of residual
weights, rwt
for measuring convergence of these iterative solvers.
In the case of ARKStepResStolerance()
, this vector has components
rwt[i] = 1.0/(reltol*abs(My[i]) + rabstol);
whereas in the case of ARKStepResVtolerance()
the vector components
are given by
rwt[i] = 1.0/(reltol*abs(My[i]) + rabstol[i]);
This residual weight vector is used in all iterative solver
convergence tests, which similarly use a weighted RMS norm on all
residuallike vectors \(v\):
\[\v\_{WRMS} = \left( \frac{1}{N} \sum_{i=1}^N (v_i\; rwt_i)^2 \right)^{1/2},\]
where \(N\) is the problem dimension.
As with the error weight vector, the user may supply a custom function
to supply the rwt
vector, through a call to
ARKStepResFtolerance()
. Further information on all three of
these functions is provided below.

int
ARKStepResStolerance
(void* arkode_mem, realtype abstol)
This function specifies a scalar absolute residual tolerance.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 rabstol – scalar absolute residual tolerance.
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL
 ARK_NO_MALLOC if the ARKStep memory was not allocated by the timestepping module
 ARK_ILL_INPUT if an argument has an illegal value (e.g. a negative tolerance).

int
ARKStepResVtolerance
(void* arkode_mem, N_Vector rabstol)
This function specifies a vector of absolute residual tolerances.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 rabstol – vector containing the absolute residual
tolerances for each solution component.
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL
 ARK_NO_MALLOC if the ARKStep memory was not allocated by the timestepping module
 ARK_ILL_INPUT if an argument has an illegal value (e.g. a negative tolerance).

int
ARKStepResFtolerance
(void* arkode_mem, ARKRwtFn rfun)
This function specifies a usersupplied function rfun to compute
the residual weight vector rwt
.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 rfun – the name of the function (of type
ARKRwtFn()
)
that implements the residual weight vector computation.
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL
 ARK_NO_MALLOC if the ARKStep memory was not allocated by the timestepping module
General advice on the choice of tolerances
For many users, the appropriate choices for tolerance values in
reltol
, abstol
, and rabstol
are a concern. The following pieces
of advice are relevant.
 The scalar relative tolerance
reltol
is to be set to control
relative errors. So a value of \(10^{4}\) means that errors
are controlled to .01%. We do not recommend using reltol
larger
than \(10^{3}\). On the other hand, reltol
should not be so
small that it is comparable to the unit roundoff of the machine
arithmetic (generally around \(10^{15}\) for doubleprecision).
 The absolute tolerances
abstol
(whether scalar or vector) need
to be set to control absolute errors when any components of the
solution vector \(y\) may be so small that pure relative error
control is meaningless. For example, if \(y_i\) starts at some
nonzero value, but in time decays to zero, then pure relative
error control on \(y_i\) makes no sense (and is overly costly)
after \(y_i\) is below some noise level. Then abstol
(if
scalar) or abstol[i]
(if a vector) needs to be set to that
noise level. If the different components have different noise
levels, then abstol
should be a vector. For example, see the
example problem ark_robertson.c
, and the discussion
of it in the ARKode Examples Documentation [R2018]. In that
problem, the three components vary between 0 and 1, and have
different noise levels; hence the atols
vector therein. It is
impossible to give any general advice on abstol
values,
because the appropriate noise levels are completely
problemdependent. The user or modeler hopefully has some idea as
to what those noise levels are.
 The residual absolute tolerances
rabstol
(whether scalar or
vector) follow a similar explanation as for abstol
, except
that these should be set to the noise level of the equation
components, i.e. the noise level of \(My\). For problems in
which \(M=I\), it is recommended that rabstol
be left
unset, which will default to the alreadysupplied abstol
values.
 Finally, it is important to pick all the tolerance values
conservatively, because they control the error committed on each
individual step. The final (global) errors are an accumulation of
those perstep errors, where that accumulation factor is
problemdependent. A general rule of thumb is to reduce the
tolerances by a factor of 10 from the actual desired limits on
errors. So if you want .01% relative accuracy (globally), a good
choice for
reltol
is \(10^{5}\). In any case, it is
a good idea to do a few experiments with the tolerances to see how
the computed solution values vary as tolerances are reduced.
Advice on controlling nonphysical negative values
In many applications, some components in the true solution are always
positive or nonnegative, though at times very small. In the
numerical solution, however, small negative (nonphysical) values
can then occur. In most cases, these values are harmless, and simply
need to be controlled, not eliminated, but in other cases any value
that violates a constraint may cause a simulation to halt. For both of
these scenarios the following pieces of advice are relevant.
 The best way to control the size of unwanted negative computed
values is with tighter absolute tolerances. Again this requires
some knowledge of the noise level of these components, which may
or may not be different for different components. Some
experimentation may be needed.
 If output plots or tables are being generated, and it is important
to avoid having negative numbers appear there (for the sake of
avoiding a long explanation of them, if nothing else), then
eliminate them, but only in the context of the output medium. Then
the internal values carried by the solver are unaffected. Remember
that a small negative value in \(y\) returned by ARKStep, with
magnitude comparable to
abstol
or less, is equivalent to zero
as far as the computation is concerned.
 The user’s righthand side routines \(f_E\) and \(f_I\)
should never change a negative value in the solution vector \(y\)
to a nonnegative value in attempt to “fix” this problem,
since this can lead to numerical instability. If the \(f_E\)
or \(f_I\) routines cannot tolerate a zero or negative value
(e.g. because there is a square root or log), then the offending
value should be changed to zero or a tiny positive number in a
temporary variable (not in the input \(y\) vector) for the
purposes of computing \(f_E(t, y)\) or \(f_I(t, y)\).
 Positivity and nonnegativity constraints on components can be
enforced by use of the recoverable error return feature in the
usersupplied righthand side functions, \(f_E\) and
\(f_I\). When a recoverable error is encountered, ARKStep will
retry the step with a smaller step size, which typically
alleviates the problem. However, because this option involves
some additional overhead cost, it should only be exercised if the
use of absolute tolerances to control the computed values is
unsuccessful.
Linear solver interface functions
As previously explained, the Newton iterations used in solving
implicit systems within ARKStep require the solution of linear
systems of the form
\[{\mathcal A}\left(z_i^{(m)}\right) \delta^{(m+1)} = G\left(z_i^{(m)}\right)\]
where
\[{\mathcal A} \approx M  \gamma J, \qquad J = \frac{\partial f_I}{\partial y}.\]
ARKode’s ARKLs linear solver interface supports all valid
SUNLinearSolver
modules for this task.
Matrixbased SUNLinearSolver
modules utilize SUNMatrix
objects
to store the approximate Jacobian matrix \(J\), the Newton matrix
\({\mathcal A}\), the mass matrix \(M\), and factorizations
used throughout the solution process.
Matrixfree SUNLinearSolver
modules instead use iterative methods
to solve the Newton systems of equations, and only require the
action of the matrix on a vector, \({\mathcal A}v\). With most
of these methods, preconditioning can be done on the left only, on the
right only, on both the left and the right, or not at all. The
exceptions to this rule are SPFGMR that supports right preconditioning
only and PCG that performs symmetric preconditioning. For the
specification of a preconditioner, see the iterative linear solver
portions of the sections Optional input functions and
Usersupplied functions.
If preconditioning is done, usersupplied functions should be used to
define left and right preconditioner matrices \(P_1\) and
\(P_2\) (either of which could be the identity matrix), such that
the product \(P_{1}P_{2}\) approximates the Newton matrix
\({\mathcal A} = M  \gamma J\).
To specify a generic linear solver for ARKStep to use for the Newton
systems, after the call to ARKStepCreate()
but before any
calls to ARKStepEvolve()
, the user’s program must create the
appropriate SUNLinearSolver
object and call the function
ARKStepSetLinearSolver()
, as documented below. To create
the SUNLinearSolver
object, the user may call one of the
SUNDIALSpackaged SUNLinSol module constructor routines via a call of
the form
SUNLinearSolver LS = SUNLinSol_*(...);
The current list of such constructor routines includes
SUNLinSol_Dense()
,
SUNLinSol_Band()
,
SUNLinSol_LapackDense()
,
SUNLinSol_LapackBand()
,
SUNLinSol_KLU()
,
SUNLinSol_SuperLUMT()
,
SUNLinSol_SPGMR()
,
SUNLinSol_SPFGMR()
,
SUNLinSol_SPBCGS()
,
SUNLinSol_SPTFQMR()
, and
SUNLinSol_PCG()
.
Alternately, a usersupplied
SUNLinearSolver
module may be created and used instead. The use
of each of the generic linear solvers involves certain constants,
functions and possibly some macros, that are likely to be needed in
the user code. These are available in the corresponding header file
associated with the specific SUNMatrix
or SUNLinearSolver
module in question, as described in the sections Matrix Data Structures and
Description of the SUNLinearSolver module.
Once this solver object has been constructed, the user should attach
it to ARKStep via a call to ARKStepSetLinearSolver()
. The
first argument passed to this function is the ARKStep memory pointer
returned by ARKStepCreate()
; the second argument is the
SUNLinearSolver
object created above. The third argument is an
optional SUNMatrix
object to accompany matrixbased
SUNLinearSolver
inputs (for matrixfree linear solvers, the third
argument should be NULL
). A call to this function initializes the
ARKLs linear solver interface, linking it to the ARKStep integrator,
and allows the user to specify additional parameters and routines
pertinent to their choice of linear solver.

int
ARKStepSetLinearSolver
(void* arkode_mem, SUNLinearSolver LS, SUNMatrix J)
This function specifies the SUNLinearSolver
object that ARKStep
should use, as well as a template Jacobian SUNMatrix
object (if
applicable).
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 LS – the
SUNLinearSolver
object to use.
 J – the template Jacobian
SUNMatrix
object to use (or
NULL
if not applicable).
 Return value:
 ARKLS_SUCCESS if successful
 ARKLS_MEM_NULL if the ARKStep memory was
NULL
 ARKLS_MEM_FAIL if there was a memory allocation failure
 ARKLS_ILL_INPUT if ARKLS is incompatible with the
provided LS or J input objects, or the current
N_Vector
module.
Notes: If LS is a matrixfree linear solver, then the J
argument should be NULL
.
If LS is a matrixbased linear solver, then the template Jacobian
matrix J will be used in the solve process, so if additional
storage is required within the SUNMatrix
object (e.g. for
factorization of a banded matrix), ensure that the input object is
allocated with sufficient size (see the documentation of
the particular SUNMATRIX type in the section Matrix Data Structures for
further information).
When using sparse linear solvers, it is typically much more
efficient to supply J so that it includes the full sparsity
pattern of the Newton system matrices \({\mathcal A} =
I\gamma J\) (or \({\mathcal A} = M\gamma J\) in the case of
nonidentity mass matrix), even if J itself has zeros in nonzero
locations of \(I\) (or \(M\)). The reasoning for this is
that \({\mathcal A}\) is constructed inplace, on top of the
userspecified values of J, so if the sparsity pattern in J is
insufficient to store \({\mathcal A}\) then it will need to be
resized internally by ARKStep.
Mass matrix solver specification functions
As discussed in section Mass matrix solver, if the ODE
system involves a nonidentity mass matrix \(M\ne I\), then ARKStep
must solve linear systems of the form
\[M x = b.\]
ARKode’s ARKLs massmatrix linear solver interface supports all valid
SUNLinearSolver
modules for this task. For iterative linear
solvers, usersupplied preconditioning can be applied. For the
specification of a preconditioner, see the iterative linear solver
portions of the sections Optional input functions and
Usersupplied functions. If preconditioning is to be
performed, usersupplied functions should be used to define left and
right preconditioner matrices \(P_1\) and \(P_2\) (either of
which could be the identity matrix), such that the product
\(P_{1}P_{2}\) approximates the mass matrix \(M\).
To specify a generic linear solver for ARKStep to use for mass matrix
systems, after the call to ARKStepCreate()
but before any
calls to ARKStepEvolve()
, the user’s program must create the
appropriate SUNLinearSolver
object and call the function
ARKStepSetMassLinearSolver()
, as documented below. The
first argument passed to this functions is the ARKStep memory
pointer returned by ARKStepCreate()
; the second argument is
the desired SUNLinearSolver
object to use for solving mass matrix
systems. The third object is a template SUNMatrix
to use with the
provided SUNLinearSolver
(if applicable). The fourth input is a
flag to indicate whether the mass matrix is timedependent,
i.e. \(M = M(t)\) or not. A call to this function initializes the
ARKLs mass matrix linear solver interface, linking this to the main
ARKStep integrator, and allows the user to specify additional
parameters and routines pertinent to their choice of linear solver.
The use of each of the generic linear solvers involves certain
constants and possibly some macros, that are likely to be needed in
the user code. These are available in the corresponding header file
associated with the specific SUNMatrix
or
SUNLinearSolver
module in question, as described in the
sections Matrix Data Structures and Description of the SUNLinearSolver module.
Note: if the user program includes linear solvers for both the
Newton and mass matrix systems, these must have the same type:
 If both are matrixbased, then they must utilize the same
SUNMatrix
type, since these will be added when forming the
Newton system matrices \({\mathcal A}\). In this case, both the
Newton and mass matrix linear solver interfaces can use the same
SUNLinearSolver
object, although different solver objects
(e.g. with different solver parameters) are also allowed.
 If both are matrixfree, then the Newton and mass matrix
SUNLinearSolver
objects must be different. These may even use
different solver algorithms (SPGMR, SPBCGS, etc.), if desired.
For example, if the mass matrix is symmetric but the Jacobian is not,
then PCG may be used for the mass matrix systems and SPGMR for the
Newton systems.
As with the Newton system solvers, the mass matrix linear system
solvers listed below are all built on top of generic SUNDIALS solver
modules.

int
ARKStepSetMassLinearSolver
(void* arkode_mem, SUNLinearSolver LS, SUNMatrix M, booleantype time_dep)
This function specifies the SUNLinearSolver
object
that ARKStep should use for mass matrix systems, as well as a
template SUNMatrix
object.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 LS – the
SUNLinearSolver
object to use.
 M – the template mass
SUNMatrix
object to use.
 time_dep – flag denoting whether the mass matrix depends on
the independent variable (\(M = M(t)\)) or not (\(M
\ne M(t)\)).
SUNTRUE
indicates timedependence of the
mass matrix.
Currently, only values of “SUNFALSE” are supported.
 Return value:
 ARKLS_SUCCESS if successful
 ARKLS_MEM_NULL if the ARKStep memory was
NULL
 ARKLS_MEM_FAIL if there was a memory allocation failure
 ARKLS_ILL_INPUT if ARKLS is incompatible with the
provided LS or M input objects, or the current
N_Vector
module.
Notes: If LS is a matrixfree linear solver, then the M
argument should be NULL
.
If LS is a matrixbased linear solver, then the template mass
matrix M will be used in the solve process, so if additional
storage is required within the SUNMatrix
object (e.g. for
factorization of a banded matrix), ensure that the input object is
allocated with sufficient size.
The time_dep flag is currently unused, serving as a placeholder
for planned future functionality. As such, ARKStep only computes
and factors the mass matrix once, with the results reused
throughout the entire ARKStep simulation.
Unlike the system Jacobian, the system mass matrix cannot be
approximated using finitedifferences of any functions provided to
ARKStep. Hence, use of the a matrixbased LS requires the user
to provide a massmatrix constructor routine (see
ARKLsMassFn
and ARKStepSetMassFn()
).
Similarly, the system mass matrixvectorproduct cannot be
approximated using finitedifferences of any functions
provided to ARKStep. Hence, use of a matrixfree LS requires the
user to provide a massmatrixtimesvector product routine (see
ARKLsMassTimesVecFn
and ARKStepSetMassTimes()
).
Nonlinear solver interface functions
When changing the nonlinear solver in ARKStep, after the
call to ARKStepCreate()
but before any calls to
ARKStepEvolve()
, the user’s program must create the
appropriate SUNNonlinSol object and call
ARKStepSetNonlinearSolver()
, as documented below. If any
calls to ARKStepEvolve()
have been made, then ARKStep will
need to be reinitialized by calling ARKStepReInit()
to
ensure that the nonlinear solver is initialized correctly before any
subsequent calls to ARKStepEvolve()
.
The first argument passed to the routine
ARKStepSetNonlinearSolver()
is the ARKStep memory pointer
returned by ARKStepCreate()
; the second argument passed
to this function is the desired SUNNonlinSol object to use for solving
the nonlinear system for each implicit stage. A call to this function
attaches the nonlinear solver to the main ARKStep integrator.

int
ARKStepSetNonlinearSolver
(void* arkode_mem, SUNNonlinearSolver NLS)
This function specifies the SUNNonlinearSolver
object
that ARKStep should use for implicit stage solves.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 NLS – the
SUNNonlinearSolver
object to use.
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL
 ARK_MEM_FAIL if there was a memory allocation failure
 ARK_ILL_INPUT if ARKStep is incompatible with the
provided NLS input object.
Notes: ARKStep will use the Newton SUNNonlinSol module by
default; a call to this routine replaces that module with the
supplied NLS object.
Rootfinding initialization function
As described in the section Rootfinding, while
solving the IVP, ARKode’s timestepping modules have the capability to
find the roots of a set of userdefined functions. To activate the
rootfinding algorithm, call the following function. This is normally
called only once, prior to the first call to
ARKStepEvolve()
, but if the rootfinding problem is to be
changed during the solution, ARKStepRootInit()
can also be
called prior to a continuation call to ARKStepEvolve()
.

int
ARKStepRootInit
(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
ARKStepCreate()
, and before ARKStepEvolve()
.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 nrtfn – number of functions \(g_i\), an integer \(\ge\) 0.
 g – name of usersupplied function, of type
ARKRootFn()
,
defining the functions \(g_i\) whose roots are sought.
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep 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
.
Notes: To disable the rootfinding feature after it has already
been initialized, or to free memory associated with ARKStep’s
rootfinding module, call ARKStepRootInit with nrtfn = 0.
Similarly, if a new IVP is to be solved with a call to
ARKStepReInit()
, where the new IVP has no rootfinding
problem but the prior one did, then call ARKStepRootInit with
nrtfn = 0.
ARKStep 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 ARKStep 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 ARKStepSetStopTime()
) or
has requested rootfinding.

int
ARKStepEvolve
(void* arkode_mem, realtype tout, N_Vector yout, realtype *tret, int itask)
Integrates the ODE over an interval in \(t\).
 Arguments:
arkode_mem – pointer to the ARKStep 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 userspecified output
time, tout, in the direction of integration,
i.e. \(t_{n1} <\) tout \(\le t_{n}\) for forward
integration, or \(t_{n} \le\) tout \(< t_{n1}\) 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 the section
Interpolation).
The ARK_ONE_STEP option tells the solver to only take a
single internal step \(y_{n1} \to y_{n}\) and then return
control back to the calling program. If this step will
overtake tout then the solver will again return an
interpolated result; otherwise it will return a copy of the
internal solution \(y_{n}\) in the vector yout
 Return value:
 ARK_SUCCESS if successful.
 ARK_ROOT_RETURN if
ARKStepEvolve()
succeeded, and
found one or more roots. If the number of root functions,
nrtfn, is greater than 1, call
ARKStepGetRootInfo()
to see which \(g_i\) were
found to have a root at (*tret).
 ARK_TSTOP_RETURN if
ARKStepEvolve()
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
ARKStepEvolve()
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:
 A component of the error weight vector became zero during
internal timestepping.
 The linear solver initialization function (called by the
user after calling
ARKStepCreate()
) failed to set
the linear solverspecific lsolve field in
arkode_mem.
 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_TOO_MUCH_ACC if the solver could not satisfy the accuracy
demanded by the user for some internal step.
 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_CONV_FAILURE if either convergence test failures occurred
too many times (ark_maxncf) during one internal time step or
occurred with \(h = h_{min}\).
 ARK_LINIT_FAIL if the linear solver’s initialization
function failed.
 ARK_LSETUP_FAIL if the linear solver’s setup routine failed in
an unrecoverable manner.
 ARK_LSOLVE_FAIL if the linear solver’s solve routine failed in
an unrecoverable manner.
 ARK_MASSINIT_FAIL if the mass matrix solver’s
initialization function failed.
 ARK_MASSSETUP_FAIL if the mass matrix solver’s setup routine
failed.
 ARK_MASSSOLVE_FAIL if the mass matrix solver’s solve routine
failed.
 ARK_VECTOROP_ERR a vector operation error occured.
Notes: The input vector yout can use the same memory as the
vector y0 of initial conditions that was passed to
ARKStepCreate()
.
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
ARKStepEvolve()
failures.
Since interpolation may reduce the accuracy in the reported
solution, if full method accuracy is desired the user should issue
a call to ARKStepSetStopTime()
before the call to
ARKStepEvolve()
to specify a fixed stop time to
end the time step and return to the user. Upon return from
ARKStepEvolve()
, 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 reenabled only though a new call
to ARKStepSetStopTime()
).
On any error return in which one or more internal steps were taken
by ARKStepEvolve()
, 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.
Interpolated output function
An optional function ARKStepGetDky()
is available to obtain
additional values of solutionrelated quantities. This function
should only be called after a successful return from
ARKStepEvolve()
, as it provides interpolated values either of
\(y\) or of its derivatives (up to the 5th derivative)
interpolated to any value of \(t\) in the last internal step taken
by ARKStepEvolve()
. Internally, this dense output algorithm is
identical to the algorithm used for the maximum order implicit
predictors, described in the section
Maximum order predictor, except that derivatives of the
polynomial model may be evaluated upon request.

int
ARKStepGetDky
(void* arkode_mem, realtype t, int k, N_Vector dky)
Computes the kth derivative of the function
\(y\) at the time t,
i.e. \(\frac{d^{(k)}}{dt^{(k)}}y(t)\), for values of the
independent variable satisfying \(t_nh_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. This
routine uses an interpolating polynomial of degree max(dord, k),
where dord is the argument provided to
ARKStepSetDenseOrder()
. The user may request k in the
range {0,...,*dord*}.
 Arguments:
 arkode_mem – pointer to the ARKStep 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 value:
 ARK_SUCCESS if successful
 ARK_BAD_K if k is not in the range {0,...,*dord*}.
 ARK_BAD_T if t is not in the interval \([t_nh_n, t_n]\)
 ARK_BAD_DKY if the dky vector was
NULL
 ARK_MEM_NULL if the ARKStep memory is
NULL
Notes: It is only legal to call this function after a successful
return from ARKStepEvolve()
.
A user may access the values \(t_n\) and \(h_n\) via the
functions ARKStepGetCurrentTime()
and
ARKStepGetLastStep()
, respectively.
Optional output functions
ARKStep provides an extensive set of functions that can be used to
obtain solver performance information. We organize these into groups:
 SUNDIALS version information accessor routines are in the subsection
SUNDIALS version information,
 General ARKStep output routines are in the subsection
Main solver optional output functions,
 ARKStep implicit solver output routines are in the subsection
Implicit solver optional output functions,
 Output routines regarding rootfinding results are in the subsection
Rootfinding optional output functions,
 Linear solver output routines are in the subsection
Linear solver interface optional output functions and
 General usability routines (e.g. to print the current ARKStep
parameters, or output the current Butcher table(s)) are in the
subsection General usability functions.
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
ARKStep. For example:
 The counters nsteps, nfe_evals, nfi_evals 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.
 The ratio nniters/nsteps measures the performance of the
nonlinear iteration in solving the nonlinear systems at each stage,
providing a measure of the degree of nonlinearity in the problem.
Typical values of this for a Newton solver on a general problem
range from 1.1 to 1.8.
 When using a Newton nonlinear solver, the ratio njevals/nniters
(in the case of a direct linear solver), and the ratio
npevals/nniters (in the case of an iterative linear solver)
can measure the overall degree of nonlinearity in the problem,
since these are updated infrequently, unless the Newton method
convergence slows.
 When using a Newton nonlinear solver, the ratio njevals/nniters
(when using a direct linear solver), and the ratio
nliters/nniters (when using an iterative linear solver) can
indicate the quality of the approximate Jacobian or preconditioner being
used. For example, if this ratio is larger for a usersupplied
Jacobian or Jacobianvector product routine than for the
differencequotient routine, it can indicate that the usersupplied
Jacobian is inaccurate.
 The ratio expsteps/accsteps can measure the quality of the ImEx
splitting used, since a higherquality splitting will be dominated
by accuracylimited steps.
 The ratio nsteps/step_attempts can measure the quality of the
time step adaptivity algorithm, since a poor algorithm will result
in more failed steps, and hence a lower ratio.
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.
Main solver optional output functions

int
ARKStepGetWorkSpace
(void* arkode_mem, long int* lenrw, long int* leniw)
Returns the ARKStep real and integer workspace sizes.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 lenrw – the number of
realtype
values in the ARKStep workspace.
 leniw – the number of integer values in the ARKStep workspace.
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL

int
ARKStepGetNumSteps
(void* arkode_mem, long int* nsteps)
Returns the cumulative number of internal steps taken by
the solver (so far).
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 nsteps – number of steps taken in the solver.
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL

int
ARKStepGetActualInitStep
(void* arkode_mem, realtype* hinused)
Returns the value of the integration step size used on the first step.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 hinused – actual value of initial step size.
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL
Notes: Even if the value of the initial integration step was
specified by the user through a call to
ARKStepSetInitStep()
, this value may have been changed by
ARKStep to ensure that the step size fell within the prescribed
bounds \((h_{min} \le h_0 \le h_{max})\), or to satisfy the
local error test condition, or to ensure convergence of the
nonlinear solver.

int
ARKStepGetLastStep
(void* arkode_mem, realtype* hlast)
Returns the integration step size taken on the last successful
internal step.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 hlast – step size taken on the last internal step.
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL

int
ARKStepGetCurrentStep
(void* arkode_mem, realtype* hcur)
Returns the integration step size to be attempted on the next internal step.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 hcur – step size to be attempted on the next internal step.
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL

int
ARKStepGetCurrentTime
(void* arkode_mem, realtype* tcur)
Returns the current internal time reached by the solver.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 tcur – current internal time reached.
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL

int
ARKStepGetTolScaleFactor
(void* arkode_mem, realtype* tolsfac)
Returns a suggested factor by which the user’s
tolerances should be scaled when too much accuracy has been
requested for some internal step.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 tolsfac – suggested scaling factor for usersupplied tolerances.
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL

int
ARKStepGetErrWeights
(void* arkode_mem, N_Vector eweight)
Returns the current error weight vector.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 eweight – solution error weights at the current time.
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL
Notes: The user must allocate space for eweight, that will be
filled in by this function.

int
ARKStepGetResWeights
(void* arkode_mem, N_Vector rweight)
Returns the current residual weight vector.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 rweight – residual error weights at the current time.
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL
Notes: The user must allocate space for rweight, that will be
filled in by this function.

int
ARKStepGetStepStats
(void* arkode_mem, long int* nsteps, realtype* hinused, realtype* hlast, realtype* hcur, realtype* tcur)
Returns many of the most useful optional outputs in a single call.
 Arguments:
 arkode_mem – pointer to the ARKStep 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 value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL

char *
ARKStepGetReturnFlagName
(long int flag)
Returns the name of the ARKStep constant corresponding to flag.
 Arguments:
 flag – a return flag from an ARKStep function.
Return value:
The return value is a string containing the name of
the corresponding constant.

int
ARKStepGetNumExpSteps
(void* arkode_mem, long int* expsteps)
Returns the cumulative number of stabilitylimited steps
taken by the solver (so far).
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 expsteps – number of stabilitylimited steps taken in the solver.
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL

int
ARKStepGetNumAccSteps
(void* arkode_mem, long int* accsteps)
Returns the cumulative number of accuracylimited steps
taken by the solver (so far).
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 accsteps – number of accuracylimited steps taken in the solver.
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL

int
ARKStepGetNumStepAttempts
(void* arkode_mem, long int* step_attempts)
Returns the cumulative number of steps attempted by the solver (so far).
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 step_attempts – number of steps attempted by solver.
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL

int
ARKStepGetNumRhsEvals
(void* arkode_mem, long int* nfe_evals, long int* nfi_evals)
Returns the number of calls to the user’s righthand
side functions, \(f_E\) and \(f_I\) (so far).
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 nfe_evals – number of calls to the user’s \(f_E(t,y)\) function.
 nfi_evals – number of calls to the user’s \(f_I(t,y)\) function.
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL
Notes: The nfi_evals value does not account for calls made to
\(f_I\) by a linear solver or preconditioner module.

int
ARKStepGetNumErrTestFails
(void* arkode_mem, long int* netfails)
Returns the number of local error test failures that
have occurred (so far).
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 netfails – number of error test failures.
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL

int
ARKStepGetCurrentButcherTables
(void* arkode_mem, ARKodeButcherTable *Bi, ARKodepButcherTable *Be)
Returns the explicit and implicit Butcher tables
currently in use by the solver.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 Bi – pointer to implicit Butcher table structure.
 Be – pointer to explicit Butcher table structure.
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL
Notes: The ARKodeButcherTable
data structure is defined as a
pointer to the following C structure:
typedef struct ARKStepButcherTableMem {
int q; /* method order of accuracy */
int p; /* embedding order of accuracy */
int stages; /* number of stages */
realtype **A; /* Butcher table coefficients */
realtype *c; /* canopy node coefficients */
realtype *b; /* root node coefficients */
realtype *d; /* embedding coefficients */
} *ARKStepButcherTable;
For more details see Butcher Table Data Structure.

int
ARKStepGetEstLocalErrors
(void* arkode_mem, N_Vector ele)
Returns the vector of estimated local truncation errors
for the current step.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 ele – vector of estimated local truncation errors.
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL
Notes: The user must allocate space for ele, that will be
filled in by this function.
The values returned in ele are valid only after a successful call
to ARKStepEvolve()
(i.e. it returned a nonnegative value).
The ele vector, together with the eweight vector from
ARKStepGetErrWeights()
, can be used to determine how the
various components of the system contributed to the estimated local
error test. Specifically, that error test uses the WRMS norm of a
vector whose components are the products of the components of these
two vectors. Thus, for example, if there were recent error test
failures, the components causing the failures are those with largest
values for the products, denoted loosely as eweight[i]*ele[i]
.

int
ARKStepGetTimestepperStats
(void* arkode_mem, long int* expsteps, long int* accsteps, long int* step_attempts, long int* nfe_evals, long int* nfi_evals, long int* nlinsetups, long int* netfails)
Returns many of the most useful timestepper statistics in a single call.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 expsteps – number of stabilitylimited steps taken in the solver.
 accsteps – number of accuracylimited steps taken in the solver.
 step_attempts – number of steps attempted by the solver.
 nfe_evals – number of calls to the user’s \(f_E(t,y)\) function.
 nfi_evals – number of calls to the user’s \(f_I(t,y)\) function.
 nlinsetups – number of linear solver setup calls made.
 netfails – number of error test failures.
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL
Implicit solver optional output functions

int
ARKStepGetNumLinSolvSetups
(void* arkode_mem, long int* nlinsetups)
Returns the number of calls made to the linear solver’s
setup routine (so far).
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 nlinsetups – number of linear solver setup calls made.
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL
Notes: This is only accumulated for the ‘life’ of the nonlinear
solver object; the counter is reset whenever a new nonlinear solver
module is ‘attached’ to ARKStep, or when ARKStep is resized.

int
ARKStepGetNumNonlinSolvIters
(void* arkode_mem, long int* nniters)
Returns the number of nonlinear solver iterations
performed (so far).
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 nniters – number of nonlinear iterations performed.
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL
 ARK_NLS_OP_ERR if the SUNNONLINSOL object returned a failure flag
Notes: This is only accumulated for the ‘life’ of the nonlinear
solver object; the counter is reset whenever a new nonlinear solver
module is ‘attached’ to ARKStep, or when ARKStep is resized.

int
ARKStepGetNumNonlinSolvConvFails
(void* arkode_mem, long int* nncfails)
Returns the number of nonlinear solver convergence
failures that have occurred (so far).
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 nncfails – number of nonlinear convergence failures.
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL
Notes: This is only accumulated for the ‘life’ of the nonlinear
solver object; the counter is reset whenever a new nonlinear solver
module is ‘attached’ to ARKStep, or when ARKStep is resized.

int
ARKStepGetNonlinSolvStats
(void* arkode_mem, long int* nniters, long int* nncfails)
Returns all of the nonlinear solver statistics in a single call.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 nniters – number of nonlinear iterations performed.
 nncfails – number of nonlinear convergence failures.
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL
 ARK_NLS_OP_ERR if the SUNNONLINSOL object returned a failure flag
Notes: These are only accumulated for the ‘life’ of the
nonlinear solver object; the counters are reset whenever a new
nonlinear solver module is ‘attached’ to ARKStep, or when ARKStep is resized.
Rootfinding optional output functions

int
ARKStepGetRootInfo
(void* arkode_mem, int* rootsfound)
Returns an array showing which functions were found to
have a root.
 Arguments:
 arkode_mem – pointer to the ARKStep 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
ARKStepRootInit()
). For \(i = 0 \ldots\)
nrtfn1, rootsfound[i]
is nonzero if \(g_i\) has a
root, and 0 if not.
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL
Notes: The user must allocate space for rootsfound prior to
calling this function.
For the components of \(g_i\) for which a root was found, the
sign of rootsfound[i]
indicates the direction of
zerocrossing. A value of +1 indicates that \(g_i\) is
increasing, while a value of 1 indicates a decreasing \(g_i\).

int
ARKStepGetNumGEvals
(void* arkode_mem, long int* ngevals)
Returns the cumulative number of calls made to the
user’s root function \(g\).
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 ngevals – number of calls made to \(g\) so far.
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL
Linear solver interface optional output functions
The following optional outputs are available from the ARKLS
modules:
workspace requirements,
number of calls to the Jacobian routine,
number of calls to the mass matrix routine,
number of calls to the implicit righthand side routine for finitedifference Jacobian approximation or Jacobianvector product approximation,
number of linear iterations,
number of linear convergence failures,
number of calls to the preconditioner setup and solve routines,
number of calls to the Jacobianvector setup and product routines,
number of calls to the massmatrixvector setup and product routines,
and last return value from an ARKLS function.
Note that, where the name of an output would otherwise conflict with the
name of an optional output from the main solver, a suffix LS (for
Linear Solver) or MLS (for Mass Linear Solver) has been added here
(e.g. lenrwLS).

int
ARKStepGetLinWorkSpace
(void* arkode_mem, long int* lenrwLS, long int* leniwLS)
Returns the real and integer workspace used by the ARKLS linear solver interface.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 lenrwLS – the number of
realtype
values in the ARKLS workspace.
 leniwLS – the number of integer values in the ARKLS workspace.
 Return value:
 ARKLS_SUCCESS if successful
 ARKLS_MEM_NULL if the ARKStep memory was
NULL
 ARKLS_LMEM_NULL if the linear solver memory was
NULL
Notes: The workspace requirements reported by this routine
correspond only to memory allocated within this interface and to
memory allocated by the SUNLinearSolver
object attached
to it. The template Jacobian matrix allocated by the user outside
of ARKLS is not included in this report.
In a parallel setting, the above values are global (i.e. summed over all
processors).

int
ARKStepGetNumJacEvals
(void* arkode_mem, long int* njevals)
Returns the number of calls made to the Jacobian approximation routine.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 njevals – number of calls to the Jacobian function.
 Return value:
 ARKLS_SUCCESS if successful
 ARKLS_MEM_NULL if the ARKStep memory was
NULL
 ARKLS_LMEM_NULL if the linear solver memory was
NULL

int
ARKStepGetNumPrecEvals
(void* arkode_mem, long int* npevals)
Returns the total number of preconditioner evaluations,
i.e. the number of calls made to psetup with jok = SUNFALSE
.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 npevals – the current number of calls to psetup.
 Return value:
 ARKLS_SUCCESS if successful
 ARKLS_MEM_NULL if the ARKStep memory was
NULL
 ARKLS_LMEM_NULL if the linear solver memory was
NULL

int
ARKStepGetNumPrecSolves
(void* arkode_mem, long int* npsolves)
Returns the number of calls made to the preconditioner
solve function, psolve.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 npsolves – the number of calls to psolve.
 Return value:
 ARKLS_SUCCESS if successful
 ARKLS_MEM_NULL if the ARKStep memory was
NULL
 ARKLS_LMEM_NULL if the linear solver memory was
NULL

int
ARKStepGetNumLinIters
(void* arkode_mem, long int* nliters)
Returns the cumulative number of linear iterations.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 nliters – the current number of linear iterations.
 Return value:
 ARKLS_SUCCESS if successful
 ARKLS_MEM_NULL if the ARKStep memory was
NULL
 ARKLS_LMEM_NULL if the linear solver memory was
NULL
Notes: This is only accumulated for the ‘life’ of the linear
solver object; the counter is reset whenever a new linear solver
module is ‘attached’ to ARKStep, or when ARKStep is resized.

int
ARKStepGetNumLinConvFails
(void* arkode_mem, long int* nlcfails)
Returns the cumulative number of linear convergence failures.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 nlcfails – the current number of linear convergence failures.
 Return value:
 ARKLS_SUCCESS if successful
 ARKLS_MEM_NULL if the ARKStep memory was
NULL
 ARKLS_LMEM_NULL if the linear solver memory was
NULL

int
ARKStepGetNumJTSetupEvals
(void* arkode_mem, long int* njtsetup)
Returns the cumulative number of calls made to the usersupplied
Jacobianvector setup function, jtsetup.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 njtsetup – the current number of calls to jtsetup.
 Return value:
 ARKLS_SUCCESS if successful
 ARKLS_MEM_NULL if the ARKStep memory was
NULL
 ARKLS_LMEM_NULL if the linear solver memory was
NULL

int
ARKStepGetNumJtimesEvals
(void* arkode_mem, long int* njvevals)
Returns the cumulative number of calls made to the
Jacobianvector product function, jtimes.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 njvevals – the current number of calls to jtimes.
 Return value:
 ARKLS_SUCCESS if successful
 ARKLS_MEM_NULL if the ARKStep memory was
NULL
 ARKLS_LMEM_NULL if the linear solver memory was
NULL

int
ARKStepGetNumLinRhsEvals
(void* arkode_mem, long int* nfevalsLS)
Returns the number of calls to the usersupplied implicit
righthand side function \(f_I\) for finite difference
Jacobian or Jacobianvector product approximation.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 nfevalsLS – the number of calls to the user implicit
righthand side function.
 Return value:
 ARKLS_SUCCESS if successful
 ARKLS_MEM_NULL if the ARKStep memory was
NULL
 ARKLS_LMEM_NULL if the linear solver memory was
NULL
Notes: The value nfevalsLS is incremented only if the default
internal difference quotient function is used.

int
ARKStepGetLastLinFlag
(void* arkode_mem, long int* lsflag)
Returns the last return value from an ARKLS routine.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 lsflag – the value of the last return flag from an
ARKLS function.
 Return value:
 ARKLS_SUCCESS if successful
 ARKLS_MEM_NULL if the ARKStep memory was
NULL
 ARKLS_LMEM_NULL if the linear solver memory was
NULL
Notes: If the ARKLs setup function failed when using the
SUNLINSOL_DENSE
or SUNLINSOL_BAND
modules, then the value
of lsflag is equal to the column index (numbered from one) at
which a zero diagonal element was encountered during the LU
factorization of the (dense or banded) Jacobian matrix. For all
other failures, lsflag is negative.
Otherwise, if the ARKLs setup function failed
(ARKStepEvolve()
returned ARK_LSETUP_FAIL), then
lsflag will be SUNLS_PSET_FAIL_UNREC, SUNLS_ASET_FAIL_UNREC
or SUNLS_PACKAGE_FAIL_UNREC.
If the ARKLS solve function failed (ARKStepEvolve()
returned ARK_LSOLVE_FAIL), then lsflag contains the error
return flag from the SUNLinearSolver
object, which will
be one of:
SUNLS_MEM_NULL, indicating that the SUNLinearSolver
memory is NULL
;
SUNLS_ATIMES_FAIL_UNREC, indicating an unrecoverable failure in
the \(Jv\) function;
SUNLS_PSOLVE_FAIL_UNREC, indicating that the preconditioner solve
function failed unrecoverably;
SUNLS_GS_FAIL, indicating a failure in the GramSchmidt procedure
(SPGMR and SPFGMR only);
SUNLS_QRSOL_FAIL, indicating that the matrix \(R\) was found
to be singular during the QR solve phase (SPGMR and SPFGMR only); or
SUNLS_PACKAGE_FAIL_UNREC, indicating an unrecoverable failure in
an external iterative linear solver package.

char *
ARKStepGetLinReturnFlagName
(long int lsflag)
Returns the name of the ARKLS constant corresponding to lsflag.
 Arguments:
 lsflag – a return flag from an ARKLS function.
Return value: The return value is a string containing the name of
the corresponding constant. If using the SUNLINSOL_DENSE
or
SUNLINSOL_BAND
modules, then if 1 \(\le\) lsflag
\(\le n\) (LU factorization failed), this routine returns “NONE”.

int
ARKStepGetMassWorkSpace
(void* arkode_mem, long int* lenrwMLS, long int* leniwMLS)
Returns the real and integer workspace used by the ARKLS mass matrix linear solver interface.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 lenrwMLS – the number of
realtype
values in the ARKLS mass solver workspace.
 leniwMLS – the number of integer values in the ARKLS mass solver workspace.
 Return value:
 ARKLS_SUCCESS if successful
 ARKLS_MEM_NULL if the ARKStep memory was
NULL
 ARKLS_LMEM_NULL if the linear solver memory was
NULL
Notes: The workspace requirements reported by this routine
correspond only to memory allocated within this interface and to
memory allocated by the SUNLinearSolver
object attached
to it. The template mass matrix allocated by the user outside
of ARKLS is not included in this report.
In a parallel setting, the above values are global (i.e. summed over all
processors).

int
ARKStepGetNumMassSetups
(void* arkode_mem, long int* nmsetups)
Returns the number of calls made to the ARKLS mass matrix solver
‘setup’ routine; these include all calls to the usersupplied
massmatrix constructor function.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 nmsetups – number of calls to the mass matrix solver setup routine.
 Return value:
 ARKLS_SUCCESS if successful
 ARKLS_MEM_NULL if the ARKStep memory was
NULL
 ARKLS_LMEM_NULL if the linear solver memory was
NULL

int
ARKStepGetNumMassMult
(void* arkode_mem, long int* nmmults)
Returns the number of calls made to the ARKLS mass matrix ‘matvec’
routine (matrixbased solvers) or the usersupplied mtimes
routine (matrisfree solvers).
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 nmmults – number of calls to the mass matrix solver matrixtimesvector routine.
 Return value:
 ARKLS_SUCCESS if successful
 ARKLS_MEM_NULL if the ARKStep memory was
NULL
 ARKLS_LMEM_NULL if the linear solver memory was
NULL

int
ARKStepGetNumMassSolves
(void* arkode_mem, long int* nmsolves)
Returns the number of calls made to the ARKLS mass matrix solver ‘solve’ routine.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 nmsolves – number of calls to the mass matrix solver solve routine.
 Return value:
 ARKLS_SUCCESS if successful
 ARKLS_MEM_NULL if the ARKStep memory was
NULL
 ARKLS_LMEM_NULL if the linear solver memory was
NULL

int
ARKStepGetNumMassPrecEvals
(void* arkode_mem, long int* nmpevals)
Returns the total number of mass matrix preconditioner evaluations,
i.e. the number of calls made to psetup.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 nmpevals – the current number of calls to psetup.
 Return value:
 ARKLS_SUCCESS if successful
 ARKLS_MEM_NULL if the ARKStep memory was
NULL
 ARKLS_LMEM_NULL if the linear solver memory was
NULL

int
ARKStepGetNumMassPrecSolves
(void* arkode_mem, long int* nmpsolves)
Returns the number of calls made to the mass matrix preconditioner
solve function, psolve.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 nmpsolves – the number of calls to psolve.
 Return value:
 ARKLS_SUCCESS if successful
 ARKLS_MEM_NULL if the ARKStep memory was
NULL
 ARKLS_LMEM_NULL if the linear solver memory was
NULL

int
ARKStepGetNumMassIters
(void* arkode_mem, long int* nmiters)
Returns the cumulative number of mass matrix solver iterations.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 nmiters – the current number of mass matrix solver linear iterations.
 Return value:
 ARKLS_SUCCESS if successful
 ARKLS_MEM_NULL if the ARKStep memory was
NULL
 ARKLS_LMEM_NULL if the linear solver memory was
NULL

int
ARKStepGetNumMassConvFails
(void* arkode_mem, long int* nmcfails)
Returns the cumulative number of mass matrix solver convergence failures.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 nmcfails – the current number of mass matrix solver convergence failures.
 Return value:
 ARKLS_SUCCESS if successful
 ARKLS_MEM_NULL if the ARKStep memory was
NULL
 ARKLS_LMEM_NULL if the linear solver memory was
NULL

int
ARKStepGetNumMTSetups
(void* arkode_mem, long int* nmtsetup)
Returns the cumulative number of calls made to the usersupplied
massmatrixvector product setup function, mtsetup.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 nmtsetup – the current number of calls to mtsetup.
 Return value:
 ARKLS_SUCCESS if successful
 ARKLS_MEM_NULL if the ARKStep memory was
NULL
 ARKLS_LMEM_NULL if the linear solver memory was
NULL

int
ARKStepGetLastMassFlag
(void* arkode_mem, long int* mlsflag)
Returns the last return value from an ARKLS mass matrix interface routine.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 mlsflag – the value of the last return flag from an ARKLS
mass matrix solver interface function.
 Return value:
 ARKLS_SUCCESS if successful
 ARKLS_MEM_NULL if the ARKStep memory was
NULL
 ARKLS_LMEM_NULL if the linear solver memory was
NULL
Notes: The values of msflag for each of the various solvers
will match those described above for the function
ARKStepGetLastLSFlag()
.
General usability functions
The following optional routines may be called by a user to inquire
about existing solver parameters, to retrieve stored Butcher tables,
write the current Butcher table(s), or even to test a provided Butcher
table to determine its analytical order of accuracy. While none of
these would typically be called during the course of solving an
initial value problem, these may be useful for users wishing to better
understand ARKStep and/or specific RungeKutta methods.

int
ARKStepWriteParameters
(void* arkode_mem, FILE *fp)
Outputs all ARKStep solver parameters to the provided file pointer.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 fp – pointer to use for printing the solver parameters.
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL
Notes: 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 nonNULL value
for this pointer, since parameters for all processes would be
identical.

int
ARKStepWriteButcher
(void* arkode_mem, FILE *fp)
Outputs the current Butcher table(s) to the provided file pointer.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 fp – pointer to use for printing the Butcher table(s).
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL
Notes: The fp argument can be stdout
or stderr
, or it
may point to a specific file created using fopen
.
If ARKStep is currently configured to run in purely explicit or
purely implicit mode, this will output a single Butcher table; if
configured to run an ImEx method then both tables will be output.
When run in parallel, only one process should set a nonNULL value
for this pointer, since tables for all processes would be
identical.
ARKStep reinitialization functions
To reinitialize the ARKStep module for the solution of a new problem,
where a prior call to ARKStepCreate()
has been made, the
user must call the function ARKStepReInit()
. The new
problem must have the same size as the previous one. This routine
performs the same input checking and initializations that are done in
ARKStepCreate()
, but it performs no memory allocation as it
assumes that the existing internal memory is sufficient for the new
problem. A call to this reinitialization routine deletes the
solution history that was stored internally during the previous
integration. Following a successful call to
ARKStepReInit()
, call ARKStepEvolve()
again for
the solution of the new problem.
The use of ARKStepReInit()
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 and the problem type (explicit, implicit,
ImEx) are left unchanged.
When using the ARKStep timestepping module, if there are changes to
the linear solver specifications, the user should make the appropriate
calls to either the linear solver objects themselves, or to the
ARKLS interface routines, as described in the section
Linear solver interface functions. Otherwise, all solver inputs set
previously remain in effect.
One important use of the ARKStepReInit()
function is in the
treating of jump discontinuities in the RHS functions. 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 ARKStepReInit()
. 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 functions 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
functions (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.

int
ARKStepReInit
(void* arkode_mem, ARKRhsFn fe, ARKRhsFn fi, realtype t0, N_Vector y0)
Provides required problem specifications and reinitializes the
ARKStep timestepper module.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 fe – the name of the C function (of type
ARKRhsFn()
)
defining the explicit portion of the righthand side function in
\(M\, \dot{y} = f_E(t,y) + f_I(t,y)\).
 fi – the name of the C function (of type
ARKRhsFn()
)
defining the implicit portion of the righthand side function in
\(M\, \dot{y} = f_E(t,y) + f_I(t,y)\).
 t0 – the initial value of \(t\).
 y0 – the initial condition vector \(y(t_0)\).
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL
 ARK_MEM_FAIL if a memory allocation failed
 ARK_ILL_INPUT if an argument has an illegal value.
Notes: If an error occurred, ARKStepReInit()
also
sends an error message to the error handler function.
ARKStep system resize function
For simulations involving changes to the number of equations and
unknowns in the ODE system (e.g. when using spatiallyadaptive
PDE simulations under a methodoflines approach), the ARKStep
integrator may be “resized” between integration steps, through calls
to the ARKStepResize()
function. This function modifies
ARKStep’s internal memory structures to use the new problem size,
without destruction of the temporal adaptivity heuristics. It is
assumed that the dynamical time scales before and after the vector
resize will be comparable, so that all timestepping heuristics prior
to calling ARKStepResize()
remain valid after the call. If
instead the dynamics should be recomputed from scratch, the ARKStep
memory structure should be deleted with a call to
ARKStepFree()
, and recreated with a calls to
ARKStepCreate()
.
To aid in the vector resize operation, the user can supply a vector
resize function that will take as input a vector with the previous
size, and transform it inplace to return a corresponding vector of
the new size. If this function (of type ARKVecResizeFn()
)
is not supplied (i.e. is set to NULL
), then all existing vectors
internal to ARKStep will be destroyed and recloned from the new input
vector.
In the case that the dynamical time scale should be modified slightly
from the previous time scale, an input hscale is allowed, that will
rescale the upcoming time step by the specified factor. If a value
hscale \(\le 0\) is specified, the default of 1.0 will be used.

int
ARKStepResize
(void* arkode_mem, N_Vector ynew, realtype hscale, realtype t0, ARKVecResizeFn resize, void* resize_data)
Reinitializes ARKStep with a different state vector but with
comparable dynamical time scale.
 Arguments:
 arkode_mem – pointer to the ARKStep memory block.
 ynew – the newlysized solution vector, holding the current
dependent variable values \(y(t_0)\).
 hscale – the desired scaling factor for the dynamical time
scale (i.e. the next step will be of size h*hscale).
 t0 – the current value of the independent variable
\(t_0\) (this must be consistent with ynew).
 resize – the usersupplied vector resize function (of type
ARKVecResizeFn()
.
 resize_data – the usersupplied data structure to be passed
to resize when modifying internal ARKStep vectors.
 Return value:
 ARK_SUCCESS if successful
 ARK_MEM_NULL if the ARKStep memory was
NULL
 ARK_NO_MALLOC if arkode_mem was not allocated.
 ARK_ILL_INPUT if an argument has an illegal value.
Notes: If an error occurred, ARKStepResize()
also sends an error
message to the error handler function.
Resizing the linear solver
When using any of the SUNDIALSprovided linear solver modules, the
linear solver memory structures must also be resized. At present,
none of these include a solverspecific ‘resize’ function, so the linear
solver memory must be destroyed and reallocated following each
call to ARKStepResize()
. Moreover, the existing ARKLS
interface should then be deleted and recreated by attaching the
updated SUNLinearSolver
(and possibly SUNMatrix
) object(s)
through calls to
ARKStepSetLinearSolver()
, and
ARKStepSetMassLinearSolver()
.
If any usersupplied routines are provided to aid the linear solver
(e.g. Jacobian construction, Jacobianvector product,
massmatrixvector product, preconditioning), then the corresponding
“set” routines must be called again following the solver
respecification.
Resizing the absolute tolerance array
If using arrayvalued absolute tolerances, the absolute tolerance
vector will be invalid after the call to ARKStepResize()
, so
the new absolute tolerance vector should be reset following each
call to ARKStepResize()
through a new call to
ARKStepSVtolerances()
(and similarly to
ARKStepResVtolerance()
if that was used for the original
problem).
If scalarvalued tolerances or a tolerance function was specified
through either ARKStepSStolerances()
or
ARKStepWFtolerances()
, then these will remain valid and no
further action is necessary.
Note
For an example of ARKStepResize()
usage, see the
supplied serial C example problem, ark_heat1D_adapt.c
.