3.4.2.2. ARKStep 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 §3.4.2.2.8, 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, §3.4.2.1, 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
§3.4.2.2.8 for details).
3.4.2.2.1. ARKStep initialization and deallocation functions

void *ARKStepCreate(ARKRhsFn fe, ARKRhsFn fi, realtype t0, N_Vector y0, SUNContext sunctx)
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(t)\, y'(t) = 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(t)\, y'(t) = f^E(t,y) + f^I(t,y)\).t0 – the initial value of \(t\).
y0 – the initial condition vector \(y(t_0)\).
sunctx – the
SUNContext
object (see §2.1)
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, aNULL
pointer will be returned, and an error message will be printed tostderr
.

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
3.4.2.2.2. 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\):
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\):
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 rabstol)
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
3.4.2.2.2.1. 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 usingreltol
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. Thenabstol
(if scalar) orabstol[i]
(if a vector) needs to be set to that noise level. If the different components have different noise levels, thenabstol
should be a vector. For example, see the example problemark_robertson.c
, and the discussion of it in the ARKODE Examples Documentation [88]. In that problem, the three components vary between 0 and 1, and have different noise levels; hence theatols
vector therein. It is impossible to give any general advice onabstol
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 forabstol
, 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 thatrabstol
be left unset, which will default to the alreadysuppliedabstol
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.
3.4.2.2.2.2. 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)\).
ARKStep supports componentwise constraints on solution components, \(y_i < 0\), \(y_i \le 0\), , \(y_i > 0\), or \(y_i \ge 0\), through the usercallable function
ARKStepSetConstraints()
. At each internal time step, if any constraint is violated then ARKStep will attempt a smaller time step that should not violate this constraint. This reduced step size is chosen such that the step size is the largest possible but where the solution component satisfies the constraint.Positivity and nonnegativity constraints on components can also 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, since this reduced step size is chosen without knowledge of the solution constraint, it may be overly conservative. Thus this option involves some additional overhead cost, and should only be exercised if the above recommendations are unsuccessful.
3.4.2.2.3. 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
where
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, when using direct
solvers, the 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 §3.4.2.2.8 and
§3.4.5.
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 SUNDIALSpackaged SUNLinSol modules, and their
constructor routines, may be found in chapter §11.
Alternately, a usersupplied SUNLinearSolver
module may be created
and used. Specific information on how to create such userprovided
modules may be found in §11.1.8.
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 JacobianSUNMatrix
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 (orNULL
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 §10 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} = M\gamma J\), even if J itself has zeros in nonzero locations of \(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.
3.4.2.2.4. Mass matrix solver specification functions
As discussed in §3.2.10.6, if the ODE system involves a nonidentity mass matrix \(M\ne I\), then ARKStep must solve linear systems of the form
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 §3.4.2.2.8 and
§3.4.5. 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 function 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.
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 matrix \(\mathcal{A}\). In this case, both the Newton and mass matrix linear solver interfaces can use the sameSUNLinearSolver
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.

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 templateSUNMatrix
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.
 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.If called with time_dep set to
SUNFALSE
, then the mass matrix is only computed and factored once (or when eitherARKStepReInit()
orARKStepResize()
are called), with the results reused throughout the entire ARKStep simulation.Unlike the system Jacobian, the system mass matrix is not 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
andARKStepSetMassFn()
).Similarly, the system mass matrixvectorproduct is not 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
andARKStepSetMassTimes()
).
3.4.2.2.5. 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 SUNNonlinearSolver
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 SUNNonlinearSolver
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
SUNNonlinearSolver
module by default; a call to this routine replaces that module with the supplied NLS object.
3.4.2.2.6. Rootfinding initialization function
As described in §3.2.11, 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 beforeARKStepEvolve()
. 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.
3.4.2.2.7. ARKStep solver function
This is the central step in the solution process – the call to perform
the integration of the IVP. The input argument 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 (as described in §3.2.2).
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, callARKStepGetRootInfo()
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\).
The initial condition violates the inequality constraints.
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 occurred.
 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 toARKStepEvolve()
to specify a fixed stop time to end the time step and return to the user. Upon return fromARKStepEvolve()
, 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 toARKStepSetStopTime()
).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.
3.4.2.2.8. Optional input functions
There are numerous optional input parameters that control the behavior of ARKStep, 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 ARKStep 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 ARKStep options (Optional inputs for ARKStep),
IVP method solver options (Optional inputs for IVP method selection),
Step adaptivity solver options (Optional inputs for time step adaptivity),
Implicit stage solver options (Optional inputs for implicit stage solves),
Linear solver interface options (Linear solver interface optional input functions), and
Rootfinding options (Rootfinding optional input functions).
For the most casual use of ARKStep, relying on the default set of solver parameters, the reader can skip to section on usersupplied functions, §3.4.5.
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 an ARKStepSet***
function can generally be made
from the user’s calling program at any time and, if successful, takes effect
immediately. ARKStepSet***
functions that cannot be called at any time note
this in the “Notes:” section of the function documentation.
3.4.2.2.8.1. Optional inputs for ARKStep
Optional input 
Function name 
Default 

Return ARKStep parameters to their defaults 
internal 

Set dense output interpolation type 


Set dense output polynomial degree 
5 

Supply a pointer to a diagnostics output file 


Supply a pointer to an error output file 


Supply a custom error handler function 
internal fn 

Disable time step adaptivity (fixedstep mode) 
disabled 

Supply an initial step size to attempt 
estimated 

Maximum no. of warnings for \(t_n+h = t_n\) 
10 

Maximum no. of internal steps before tout 
500 

Maximum absolute step size 
\(\infty\) 

Minimum absolute step size 
0.0 

Set a value for \(t_{stop}\) 
N/A 

Supply a pointer for user data 


Maximum no. of ARKStep error test failures 
7 

Set ‘optimal’ adaptivity params. for a method 
internal 

Set inequality constraints on solution 


Set max number of constraint failures 
10 

int ARKStepSetDefaults(void *arkode_mem)
Resets all optional input parameters to ARKStep’s original default values.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
Does not change the user_data pointer or any parameters within the specified timestepping module.
Also leaves alone any data structures or options related to rootfinding (those can be reset using
ARKStepRootInit()
).

int ARKStepSetInterpolantType(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).
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
itype – requested interpolant type (
ARK_INTERP_HERMITE
orARK_INTERP_LAGRANGE
)
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep 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
 Notes:
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 previouslyallocated interpolation module, and recreates one according to the specified argument. Thus any previous calls to
ARKStepSetInterpolantDegree()
will be nullified.This routine may only be called after the call to
ARKStepCreate()
. After the first call toARKStepEvolve()
the interpolation type may not be changed without first callingARKStepReInit()
.If this routine is not called, the Hermite interpolation module will be used.

int ARKStepSetInterpolantDegree(void *arkode_mem, int degree)
Specifies the degree of the polynomial interpolant used for dense output (i.e. interpolation of solution output values and implicit method predictors).
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
degree – requested polynomial degree.
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory or interpolation module are
NULL
ARK_INTERP_FAIL if this is called after
ARKStepEvolve()
ARK_ILL_INPUT if an argument has an illegal value or the interpolation module has already been initialized
 Notes:
Allowed values are between 0 and 5.
This routine should be called after
ARKStepCreate()
and beforeARKStepEvolve()
. After the first call toARKStepEvolve()
the interpolation degree may not be changed without first callingARKStepReInit()
.If a user calls both this routine and
ARKStepSetInterpolantType()
, thenARKStepSetInterpolantType()
must be called first.Since the accuracy of any polynomial interpolant is limited by the accuracy of the timestep solutions on which it is based, the actual polynomial degree that is used by ARKStep will be the minimum of \(q1\) and the input degree, where \(q\) is the order of accuracy for the time integration method.

int ARKStepSetDenseOrder(void *arkode_mem, int dord)
This function is deprecated, and will be removed in a future release. Users should transition to calling
ARKStepSetInterpolantDegree()
instead.

int ARKStepSetDiagnostics(void *arkode_mem, FILE *diagfp)
Specifies the file pointer for a diagnostics file where all ARKStep step adaptivity and solver information is written.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
diagfp – pointer to the diagnostics output file.
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
This parameter can be
stdout
orstderr
, although the suggested approach is to specify a pointer to a unique file opened by the user and returned byfopen
. If not called, or if called with aNULL
file pointer, all diagnostics output is disabled.When run in parallel, only one process should set a nonNULL value for this pointer, since statistics from all processes would be identical.
Deprecated since version 5.2.0: Use
SUNLogger_SetInfoFilename()
instead.

int ARKStepSetErrFile(void *arkode_mem, FILE *errfp)
Specifies a pointer to the file where all ARKStep warning and error messages will be written if the default internal error handling function is used.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
errfp – pointer to the output file.
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
The default value for errfp is
stderr
.Passing a
NULL
value disables all future error message output (except for the case wherein the ARKStep memory pointer isNULL
). This use of the function is strongly discouraged.If used, this routine should be called before any other optional input functions, in order to take effect for subsequent error messages.

int ARKStepSetErrHandlerFn(void *arkode_mem, ARKErrHandlerFn ehfun, void *eh_data)
Specifies the optional userdefined function to be used in handling error messages.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
ehfun – name of usersupplied error handler function.
eh_data – pointer to user data passed to ehfun every time it is called.
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
Error messages indicating that the ARKStep solver memory is
NULL
will always be directed tostderr
.

int ARKStepSetFixedStep(void *arkode_mem, realtype hfixed)
Disables time step adaptivity within ARKStep, and specifies the fixed time step size to use for the following internal step(s).
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
hfixed – value of the fixed step size to use.
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
Pass 0.0 to return ARKStep to the default (adaptivestep) mode.
Use of this function is not generally recommended, since it gives no assurance of the validity of the computed solutions. It is primarily provided for codetocode verification testing purposes.
When using
ARKStepSetFixedStep()
, any values provided to the functionsARKStepSetInitStep()
,ARKStepSetAdaptivityFn()
,ARKStepSetMaxErrTestFails()
,ARKStepSetAdaptivityMethod()
,ARKStepSetCFLFraction()
,ARKStepSetErrorBias()
,ARKStepSetFixedStepBounds()
,ARKStepSetMaxCFailGrowth()
,ARKStepSetMaxEFailGrowth()
,ARKStepSetMaxFirstGrowth()
,ARKStepSetMaxGrowth()
,ARKStepSetMinReduction()
,ARKStepSetSafetyFactor()
,ARKStepSetSmallNumEFails()
andARKStepSetStabilityFn()
will be ignored, since temporal adaptivity is disabled.If both
ARKStepSetFixedStep()
andARKStepSetStopTime()
are used, then the fixed step size will be used for all steps until the final step preceding the provided stop time (which may be shorter). To resume use of the previous fixed step size, another call toARKStepSetFixedStep()
must be made prior to callingARKStepEvolve()
to resume integration.It is not recommended that
ARKStepSetFixedStep()
be used in concert withARKStepSetMaxStep()
orARKStepSetMinStep()
, since at best those latter two routines will provide no useful information to the solver, and at worst they may interfere with the desired fixed step size.

int ARKStepSetInitStep(void *arkode_mem, realtype hin)
Specifies the initial time step size ARKStep should use after initialization, reinitialization, or resetting.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
hin – value of the initial step to be attempted \((\ne 0)\).
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
Pass 0.0 to use the default value.
By default, ARKStep estimates the initial step size to be \(h = \sqrt{\dfrac{2}{\left\ \ddot{y}\right\}}\), where \(\ddot{y}\) is estimate of the second derivative of the solution at \(t_0\).
This routine will also reset the step size and error history.

int ARKStepSetMaxHnilWarns(void *arkode_mem, int mxhnil)
Specifies the maximum number of messages issued by the solver to warn that \(t+h=t\) on the next internal step, before ARKStep will instead return with an error.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
mxhnil – maximum allowed number of warning messages \((>0)\).
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
The default value is 10; set mxhnil to zero to specify this default.
A negative value indicates that no warning messages should be issued.

int ARKStepSetMaxNumSteps(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 ARKStep will return with an error.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
mxsteps – maximum allowed number of internal steps.
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
Passing mxsteps = 0 results in ARKStep using the default value (500).
Passing mxsteps < 0 disables the test (not recommended).

int ARKStepSetMaxStep(void *arkode_mem, realtype hmax)
Specifies the upper bound on the magnitude of the time step size.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
hmax – maximum absolute value of the time step size \((\ge 0)\).
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
Pass hmax \(\le 0.0\) to set the default value of \(\infty\).

int ARKStepSetMinStep(void *arkode_mem, realtype hmin)
Specifies the lower bound on the magnitude of the time step size.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
hmin – minimum absolute value of the time step size \((\ge 0)\).
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
Pass hmin \(\le 0.0\) to set the default value of 0.

int ARKStepSetStopTime(void *arkode_mem, realtype tstop)
Specifies the value of the independent variable \(t\) past which the solution is not to proceed.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
tstop – stopping time for the integrator.
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
The default is that no stop time is imposed.

int ARKStepSetUserData(void *arkode_mem, void *user_data)
Specifies the user data block user_data and attaches it to the main ARKStep memory block.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
user_data – pointer to the user data.
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
If specified, the pointer to user_data is passed to all usersupplied functions for which it is an argument; otherwise
NULL
is passed.If user_data is needed in user preconditioner functions, the call to this function must be made before any calls to
ARKStepSetLinearSolver()
and/orARKStepSetMassLinearSolver()
.

int ARKStepSetMaxErrTestFails(void *arkode_mem, int maxnef)
Specifies the maximum number of error test failures permitted in attempting one step, before returning with an error.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
maxnef – maximum allowed number of error test failures \((>0)\).
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
The default value is 7; set maxnef \(\le 0\) to specify this default.

int ARKStepSetOptimalParams(void *arkode_mem)
Sets all adaptivity and solver parameters to our “best guess” values for a given integration method type (ERK, DIRK, ARK) and a given method order.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
Should only be called after the method order and integration method have been set. The “optimal” values resulted from repeated testing of ARKStep’s solvers on a variety of training problems. However, all problems are different, so these values may not be optimal for all users.

int ARKStepSetConstraints(void *arkode_mem, N_Vector constraints)
Specifies a vector defining inequality constraints for each component of the solution vector \(y\).
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
constraints – vector of constraint flags. Each component specifies the type of solution constraint:
\[\begin{split}\texttt{constraints[i]} = \left\{ \begin{array}{rcl} 0.0 &\Rightarrow\;& \text{no constraint is imposed on}\; y_i,\\ 1.0 &\Rightarrow\;& y_i \geq 0,\\ 1.0 &\Rightarrow\;& y_i \leq 0,\\ 2.0 &\Rightarrow\;& y_i > 0,\\ 2.0 &\Rightarrow\;& y_i < 0.\\ \end{array}\right.\end{split}\]
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if the constraints vector contains illegal values
 Notes:
The presence of a non
NULL
constraints vector that is not 0.0 in all components will cause constraint checking to be performed. However, a call with 0.0 in all components ofconstraints
will result in an illegal input return. ANULL
constraints vector will disable constraint checking.After a call to
ARKStepResize()
inequality constraint checking will be disabled and a call toARKStepSetConstraints()
is required to reenable constraint checking.Since constrainthandling is performed through cutting time steps that would violate the constraints, it is possible that this feature will cause some problems to fail due to an inability to enforce constraints even at the minimum time step size. Additionally, the features
ARKStepSetConstraints()
andARKStepSetFixedStep()
are incompatible, and should not be used simultaneously.

int ARKStepSetMaxNumConstrFails(void *arkode_mem, int maxfails)
Specifies the maximum number of constraint failures in a step before ARKStep will return with an error.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
maxfails – maximum allowed number of constrain failures.
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
 Notes:
Passing maxfails <= 0 results in ARKStep using the default value (10).
3.4.2.2.8.2. Optional inputs for IVP method selection
Optional input 
Function name 
Default 

Set integrator method order 
4 

Specify implicit/explicit problem 


Specify explicit problem 


Specify implicit problem 


Set additive RK tables 
internal 

Set additive RK tables via their numbers 
internal 

Set additive RK tables via their names 
internal 

int ARKStepSetOrder(void *arkode_mem, int ord)
Specifies the order of accuracy for the ARK/DIRK/ERK integration method.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
ord – requested order of accuracy.
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
For explicit methods, the allowed values are \(2 \le\) ord \(\le 8\). For implicit methods, the allowed values are \(2\le\) ord \(\le 5\), and for ImEx methods the allowed values are \(3 \le\) ord \(\le 5\). Any illegal input will result in the default value of 4.
Since ord affects the memory requirements for the internal ARKStep memory block, it cannot be changed after the first call to
ARKStepEvolve()
, unlessARKStepReInit()
is called.

int ARKStepSetImEx(void *arkode_mem)
Specifies that both the implicit and explicit portions of problem are enabled, and to use an additive Runge–Kutta method.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
This is automatically deduced when neither of the function pointers fe or fi passed to
ARKStepCreate()
areNULL
, but may be set directly by the user if desired.

int ARKStepSetExplicit(void *arkode_mem)
Specifies that the implicit portion of problem is disabled, and to use an explicit RK method.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
This is automatically deduced when the function pointer fi passed to
ARKStepCreate()
isNULL
, but may be set directly by the user if desired.If the problem is posed in explicit form, i.e. \(\dot{y} = f(t,y)\), then we recommend that the ERKStep timestepper module be used instead.

int ARKStepSetImplicit(void *arkode_mem)
Specifies that the explicit portion of problem is disabled, and to use a diagonally implicit RK method.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
This is automatically deduced when the function pointer fe passed to
ARKStepCreate()
isNULL
, but may be set directly by the user if desired.

int ARKStepSetTables(void *arkode_mem, int q, int p, ARKodeButcherTable Bi, ARKodeButcherTable Be)
Specifies a customized Butcher table (or pair) for the ERK, DIRK, or ARK method.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
q – global order of accuracy for the ARK method.
p – global order of accuracy for the embedded ARK method.
Bi – the Butcher table for the implicit RK method.
Be – the Butcher table for the explicit RK method.
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
For a description of the
ARKodeButcherTable
type and related functions for creating Butcher tables, see §3.5.To set an explicit table, Bi must be
NULL
. This automatically callsARKStepSetExplicit()
. However, if the problem is posed in explicit form, i.e. \(\dot{y} = f(t,y)\), then we recommend that the ERKStep timestepper module be used instead of ARKStep.To set an implicit table, Be must be
NULL
. This automatically callsARKStepSetImplicit()
.If both Bi and Be are provided, this routine automatically calls
ARKStepSetImEx()
.When only one table is provided (i.e., Bi or Be is
NULL
) then the input values of q and p are ignored and the global order of the method and embedding (if applicable) are obtained from the Butcher table structures. If both Bi and Be are nonNULL (e.g, an ImEx method is provided) then the input values of q and p are used as the order of the ARK method may be less than the orders of the individual tables. No error checking is performed to ensure that either p or q correctly describe the coefficients that were input.Error checking is subsequently performed at ARKStep initialization to ensure that Bi and Be (if nonNULL) specify DIRK and ERK methods, respectively. Specifically, the A member of Bi must be lower triangular with at least one nonzero value on the diagonal, and the A member of Be must be strictly lower triangular. When both Bi and Be are nonNULL, they must agree on the number of internal stages, i.e., the stages members of both structures must match.
If the inputs Bi or Be do not contain an embedding (when the corresponding explicit or implicit table is nonNULL), the user must call
ARKStepSetFixedStep()
to enable fixedstep mode and set the desired time step size.

int ARKStepSetTableNum(void *arkode_mem, ARKODE_DIRKTableID itable, ARKODE_ERKTableID etable)
Indicates to use specific builtin Butcher tables for the ERK, DIRK or ARK method.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
itable – index of the DIRK Butcher table.
etable – index of the ERK Butcher table.
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
The allowable values for both the itable and etable arguments corresponding to builtin tables may be found in §3.7.
To choose an explicit table, set itable to a negative value. This automatically calls
ARKStepSetExplicit()
. However, if the problem is posed in explicit form, i.e. \(\dot{y} = f(t,y)\), then we recommend that the ERKStep timestepper module be used instead of ARKStep.To select an implicit table, set etable to a negative value. This automatically calls
ARKStepSetImplicit()
.If both itable and etable are nonnegative, then these should match an existing implicit/explicit pair, listed in §3.7.3. This automatically calls
ARKStepSetImEx()
.In all cases, errorchecking is performed to ensure that the tables exist.

int ARKStepSetTableName(void *arkode_mem, const char *itable, const char *etable)
Indicates to use specific builtin Butcher tables for the ERK, DIRK or ARK method.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
itable – name of the DIRK Butcher table.
etable – name of the ERK Butcher table.
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
The allowable values for both the itable and etable arguments corresponding to builtin tables may be found in §3.7. This function is case sensitive.
To choose an explicit table, set itable to
"ARKODE_DIRK_NONE"
. This automatically callsARKStepSetExplicit()
. However, if the problem is posed in explicit form, i.e. \(\dot{y} = f(t,y)\), then we recommend that the ERKStep timestepper module be used instead of ARKStep.To select an implicit table, set etable to
"ARKODE_ERK_NONE"
. This automatically callsARKStepSetImplicit()
.If both itable and etable are not none, then these should match an existing implicit/explicit pair, listed in §3.7.3. This automatically calls
ARKStepSetImEx()
.In all cases, errorchecking is performed to ensure that the tables exist.
3.4.2.2.8.3. Optional inputs for time step adaptivity
The mathematical explanation of ARKODE’s time step adaptivity algorithm, including how each of the parameters below is used within the code, is provided in §3.2.7.
Optional input 
Function name 
Default 

Set a custom time step adaptivity function 
internal 

Choose an existing time step adaptivity method 
0 

Explicit stability safety factor 
0.5 

Time step error bias factor 
1.5 

Bounds determining no change in step size 
1.0 1.5 

Maximum step growth factor on convergence fail 
0.25 

Maximum step growth factor on error test fail 
0.3 

Maximum first step growth factor 
10000.0 

Maximum allowed general step growth factor 
20.0 

Minimum allowed step reduction factor on error test fail 
0.1 

Time step safety factor 
0.96 

Error fails before MaxEFailGrowth takes effect 
2 

Explicit stability function 
none 

int ARKStepSetAdaptivityFn(void *arkode_mem, ARKAdaptFn hfun, void *h_data)
Sets a usersupplied timestep adaptivity function.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
hfun – name of usersupplied adaptivity function.
h_data – pointer to user data passed to hfun every time it is called.
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
This function should focus on accuracybased time step estimation; for stability based time steps the function
ARKStepSetStabilityFn()
should be used instead.

int ARKStepSetAdaptivityMethod(void *arkode_mem, int imethod, int idefault, int pq, realtype *adapt_params)
Specifies the method (and associated parameters) used for time step adaptivity.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
imethod – accuracybased adaptivity method choice (0 \(\le\) imethod \(\le\) 5): 0 is PID, 1 is PI, 2 is I, 3 is explicit Gustafsson, 4 is implicit Gustafsson, and 5 is the ImEx Gustafsson.
idefault – flag denoting whether to use default adaptivity parameters (1), or that they will be supplied in the adapt_params argument (0).
pq – flag denoting whether to use the embedding order of accuracy p (0) or the method order of accuracy q (1) within the adaptivity algorithm. p is the default.
adapt_params[0] – \(k_1\) parameter within accuracybased adaptivity algorithms.
adapt_params[1] – \(k_2\) parameter within accuracybased adaptivity algorithms.
adapt_params[2] – \(k_3\) parameter within accuracybased adaptivity algorithms.
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
If custom parameters are supplied, they will be checked for validity against published stability intervals. If other parameter values are desired, it is recommended to instead provide a custom function through a call to
ARKStepSetAdaptivityFn()
.

int ARKStepSetCFLFraction(void *arkode_mem, realtype cfl_frac)
Specifies the fraction of the estimated explicitly stable step to use.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
cfl_frac – maximum allowed fraction of explicitly stable step (default is 0.5).
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
Any nonpositive parameter will imply a reset to the default value.

int ARKStepSetErrorBias(void *arkode_mem, realtype bias)
Specifies the bias to be applied to the error estimates within accuracybased adaptivity strategies.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
bias – bias applied to error in accuracybased time step estimation (default is 1.5).
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
Any value below 1.0 will imply a reset to the default value.

int ARKStepSetFixedStepBounds(void *arkode_mem, realtype lb, realtype ub)
Specifies the step growth interval in which the step size will remain unchanged.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
lb – lower bound on window to leave step size fixed (default is 1.0).
ub – upper bound on window to leave step size fixed (default is 1.5).
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
Any interval not containing 1.0 will imply a reset to the default values.

int ARKStepSetMaxCFailGrowth(void *arkode_mem, realtype etacf)
Specifies the maximum step size growth factor upon an algebraic solver convergence failure on a stage solve within a step, \(\eta_{cf}\) from §3.2.10.3.1.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
etacf – time step reduction factor on a nonlinear solver convergence failure (default is 0.25).
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
Any value outside the interval \((0,1]\) will imply a reset to the default value.

int ARKStepSetMaxEFailGrowth(void *arkode_mem, realtype etamxf)
Specifies the maximum step size growth factor upon multiple successive accuracybased error failures in the solver.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
etamxf – time step reduction factor on multiple error fails (default is 0.3).
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
Any value outside the interval \((0,1]\) will imply a reset to the default value.

int ARKStepSetMaxFirstGrowth(void *arkode_mem, realtype etamx1)
Specifies the maximum allowed growth factor in step size following the very first integration step.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
etamx1 – maximum allowed growth factor after the first time step (default is 10000.0).
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
Any value \(\le 1.0\) will imply a reset to the default value.

int ARKStepSetMaxGrowth(void *arkode_mem, realtype mx_growth)
Specifies the maximum allowed growth factor in step size between consecutive steps in the integration process.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
mx_growth – maximum allowed growth factor between consecutive time steps (default is 20.0).
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
Any value \(\le 1.0\) will imply a reset to the default value.

int ARKStepSetMinReduction(void *arkode_mem, realtype eta_min)
Specifies the minimum allowed reduction factor in step size between step attempts, resulting from a temporal error failure in the integration process.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
eta_min – minimum allowed reduction factor in time step after an error test failure (default is 0.1).
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
Any value outside the interval \((0,1)\) will imply a reset to the default value.

int ARKStepSetSafetyFactor(void *arkode_mem, realtype safety)
Specifies the safety factor to be applied to the accuracybased estimated step.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
safety – safety factor applied to accuracybased time step (default is 0.96).
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
Any value \(\le 0\) will imply a reset to the default value.

int ARKStepSetSmallNumEFails(void *arkode_mem, int small_nef)
Specifies the threshold for “multiple” successive error failures before the etamxf parameter from
ARKStepSetMaxEFailGrowth()
is applied. Arguments:
arkode_mem – pointer to the ARKStep memory block.
small_nef – bound to determine ‘multiple’ for etamxf (default is 2).
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
Any value \(\le 0\) will imply a reset to the default value.

int ARKStepSetStabilityFn(void *arkode_mem, ARKExpStabFn EStab, void *estab_data)
Sets the problemdependent function to estimate a stable time step size for the explicit portion of the ODE system.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
EStab – name of usersupplied stability function.
estab_data – pointer to user data passed to EStab every time it is called.
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
This function should return an estimate of the absolute value of the maximum stable time step for the explicit portion of the ODE system. It is not required, since accuracybased adaptivity may be sufficient for retaining stability, but this can be quite useful for problems where the explicit righthand side function \(f^E(t,y)\) contains stiff terms.
3.4.2.2.8.4. Optional inputs for implicit stage solves
The mathematical explanation for the nonlinear solver strategies used by ARKStep, including how each of the parameters below is used within the code, is provided in §3.2.10.1.
Optional input 
Function name 
Default 

Specify that \(f^I\) is linearly implicit 


Specify that \(f^I\) is nonlinearly implicit 


Implicit predictor method 
0 

Userprovided implicit stage predictor 


RHS function for nonlinear system evaluations 


Maximum number of nonlinear iterations 
3 

Coefficient in the nonlinear convergence test 
0.1 

Nonlinear convergence rate constant 
0.3 

Nonlinear residual divergence ratio 
2.3 

Maximum number of convergence failures 
10 

Specify if \(f^I\) is deduced after a nonlinear solve 


int ARKStepSetLinear(void *arkode_mem, int timedepend)
Specifies that the implicit portion of the problem is linear.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
timedepend – flag denoting whether the Jacobian of \(f^I(t,y)\) is timedependent (1) or not (0).
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
Tightens the linear solver tolerances and takes only a single Newton iteration. Calls
ARKStepSetDeltaGammaMax()
to enforce Jacobian recomputation when the step size ratio changes by more than 100 times the unit roundoff (since nonlinear convergence is not tested). Only applicable when used in combination with the modified or inexact Newton iteration (not the fixedpoint solver).When \(f^I(t,y)\) is timedependent, all linear solver structures (Jacobian, preconditioner) will be updated preceding each implicit stage. Thus one must balance the relative costs of such recomputation against the benefits of requiring only a single Newton linear solve.

int ARKStepSetNonlinear(void *arkode_mem)
Specifies that the implicit portion of the problem is nonlinear.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
This is the default behavior of ARKStep, so the function is primarily useful to undo a previous call to
ARKStepSetLinear()
. CallsARKStepSetDeltaGammaMax()
to reset the step size ratio threshold to the default value.

int ARKStepSetPredictorMethod(void *arkode_mem, int method)
Specifies the method from §3.2.10.5 to use for predicting implicit solutions.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
method – method choice (0 \(\le\) method \(\le\) 4):
0 is the trivial predictor,
1 is the maximum order (dense output) predictor,
2 is the variable order predictor, that decreases the polynomial degree for more distant RK stages,
3 is the cutoff order predictor, that uses the maximum order for early RK stages, and a firstorder predictor for distant RK stages,
4 is the bootstrap predictor, that uses a secondorder predictor based on only information within the current step. deprecated
5 is the minimum correction predictor, that uses all preceding stage information within the current step for prediction. deprecated
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
The default value is 0. If method is set to an undefined value, this default predictor will be used.
Options 4 and 5 are currently not supported when solving a problem involving a nonidentity mass matrix. In that case, selection of method as 4 or 5 will instead default to the trivial predictor (method 0). Both of these options have been deprecated, and will be removed from a future release.

int ARKStepSetStagePredictFn(void *arkode_mem, ARKStagePredictFn PredictStage)
Sets the usersupplied function to update the implicit stage predictor prior to execution of the nonlinear or linear solver algorithms that compute the implicit stage solution.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
PredictStage – name of usersupplied predictor function. If
NULL
, then any previouslyprovided stage prediction function will be disabled.
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
 Notes:
See §3.4.5.7 for more information on this usersupplied routine.

int ARKStepSetNlsRhsFn(void *arkode_mem, ARKRhsFn nls_fi)
Specifies an alternative implicit righthand side function for evaluating \(f^I(t,y)\) within nonlinear system function evaluations (3.25)  (3.27).
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
nls_fi – the alternative C function for computing the righthand side function \(f^I(t,y)\) in the ODE.
 Return value:
ARK_SUCCESS if successful.
ARK_MEM_NULL if the ARKStep memory was
NULL
.
 Notes:
The default is to use the implicit righthand side function provided to
ARKStepCreate()
in nonlinear system functions. If the input implicit righthand side function isNULL
, the default is used.When using a nondefault nonlinear solver, this function must be called after
ARKStepSetNonlinearSolver()
.

int ARKStepSetMaxNonlinIters(void *arkode_mem, int maxcor)
Specifies the maximum number of nonlinear solver iterations permitted per implicit stage solve within each time step.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
maxcor – maximum allowed solver iterations per stage \((>0)\).
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value or if the SUNNONLINSOL module is
NULL
ARK_NLS_OP_ERR if the SUNNONLINSOL object returned a failure flag
 Notes:
The default value is 3; set maxcor \(\le 0\) to specify this default.

int ARKStepSetNonlinConvCoef(void *arkode_mem, realtype nlscoef)
Specifies the safety factor \(\epsilon\) used within the nonlinear solver convergence test (3.39).
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
nlscoef – coefficient in nonlinear solver convergence test \((>0.0)\).
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
The default value is 0.1; set nlscoef \(\le 0\) to specify this default.

int ARKStepSetNonlinCRDown(void *arkode_mem, realtype crdown)
Specifies the constant \(c_r\) used in estimating the nonlinear solver convergence rate (3.38).
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
crdown – nonlinear convergence rate estimation constant (default is 0.3).
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
Any nonpositive parameter will imply a reset to the default value.

int ARKStepSetNonlinRDiv(void *arkode_mem, realtype rdiv)
Specifies the nonlinear correction threshold \(r_{div}\) from (3.40), beyond which the iteration will be declared divergent.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
rdiv – tolerance on nonlinear correction size ratio to declare divergence (default is 2.3).
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
Any nonpositive parameter will imply a reset to the default value.

int ARKStepSetMaxConvFails(void *arkode_mem, int maxncf)
Specifies the maximum number of nonlinear solver convergence failures permitted during one step, \(max_{ncf}\) from §3.2.10.3.1, before ARKStep will return with an error.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
maxncf – maximum allowed nonlinear solver convergence failures per step \((>0)\).
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
The default value is 10; set maxncf \(\le 0\) to specify this default.
Upon each convergence failure, ARKStep will first call the Jacobian setup routine and try again (if a Newton method is used). If a convergence failure still occurs, the time step size is reduced by the factor etacf (set within
ARKStepSetMaxCFailGrowth()
).

int ARKStepSetDeduceImplicitRhs(void *arkode_mem, sunbooleantype deduce)
Specifies if implicit stage derivatives are deduced without evaluating \(f^I\). See §3.2.10.1 for more details.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
deduce – If
SUNFALSE
(default), the stage derivative is obtained by evaluating \(f^I\) with the stage solution returned from the nonlinear solver. IfSUNTRUE
, the stage derivative is deduced without an additional evaluation of \(f^I\).
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
New in version 5.2.0.
3.4.2.2.8.5. Linear solver interface optional input functions
The mathematical explanation of the linear solver methods available to ARKStep is provided in §3.2.10.2. We group the usercallable routines into four categories: general routines concerning the update frequency for matrices and/or preconditioners, optional inputs for matrixbased linear solvers, optional inputs for matrixfree linear solvers, and optional inputs for iterative linear solvers. We note that the matrixbased and matrixfree groups are mutually exclusive, whereas the “iterative” tag can apply to either case.
3.4.2.2.8.5.1. Optional inputs for the ARKLS linear solver interface
As discussed in §3.2.10.2.3, ARKODE strives to reuse matrix and preconditioner data for as many solves as possible to amortize the high costs of matrix construction and factorization. To that end, ARKStep provides usercallable routines to modify this behavior. Recall that the Newton system matrices that arise within an implicit stage solve are \(\mathcal{A}(t,z) \approx M(t)  \gamma J(t,z)\), where the implicit righthand side function has Jacobian matrix \(J(t,z) = \frac{\partial f^I(t,z)}{\partial z}\).
The matrix or preconditioner for \(\mathcal{A}\) can only be
updated within a call to the linear solver “setup” routine. In
general, the frequency with which the linear solver setup routine is
called may be controlled with the msbp argument to
ARKStepSetLSetupFrequency()
. When this occurs, the
validity of \(\mathcal{A}\) for successive time steps
intimately depends on whether the corresponding \(\gamma\) and
\(J\) inputs remain valid.
At each call to the linear solver setup routine the decision to update \(\mathcal{A}\) with a new value of \(\gamma\), and to reuse or reevaluate Jacobian information, depends on several factors including:
the success or failure of previous solve attempts,
the success or failure of the previous time step attempts,
the change in \(\gamma\) from the value used when constructing \(\mathcal{A}\), and
the number of steps since Jacobian information was last evaluated.
The frequency with which to update Jacobian information can be controlled
with the msbj argument to ARKStepSetJacEvalFrequency()
.
We note that this is only checked within calls to the linear solver setup
routine, so values msbj \(<\) msbp do not make sense. For
linearsolvers with usersupplied preconditioning the above factors are used
to determine whether to recommend updating the Jacobian information in the
preconditioner (i.e., whether to set jok to SUNFALSE
in calling the
usersupplied ARKLsPrecSetupFn()
). For matrixbased linear solvers
these factors determine whether the matrix \(J(t,y) = \frac{\partial f^I(t,y)}{\partial y}\)
should be updated (either with an internal finite difference approximation or
a call to the usersupplied ARKLsJacFn
); if not then the previous
value is reused and the system matrix \(\mathcal{A}(t,y) \approx M(t)  \gamma J(t,y)\)
is recomputed using the current \(\gamma\) value.
Optional input 
Function name 
Default 

Max change in step signaling new \(J\) 
0.2 

Linear solver setup frequency 
20 

Jacobian / preconditioner update frequency 
51 

int ARKStepSetDeltaGammaMax(void *arkode_mem, realtype dgmax)
Specifies a scaled step size ratio tolerance, \(\Delta\gamma_{max}\) from §3.2.10.2.3, beyond which the linear solver setup routine will be signaled.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
dgmax – tolerance on step size ratio change before calling linear solver setup routine (default is 0.2).
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
Any nonpositive parameter will imply a reset to the default value.

int ARKStepSetLSetupFrequency(void *arkode_mem, int msbp)
Specifies the frequency of calls to the linear solver setup routine, \(msbp\) from §3.2.10.2.3.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
msbp – the linear solver setup frequency.
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
 Notes:
Positive values of msbp specify the linear solver setup frequency. For example, an input of 1 means the setup function will be called every time step while an input of 2 means it will be called called every other time step. If msbp is 0, the default value of 20 will be used. A negative value forces a linear solver step at each implicit stage.

int ARKStepSetJacEvalFrequency(void *arkode_mem, long int msbj)
Specifies the frequency for recomputing the Jacobian or recommending a preconditioner update, \(msbj\) from §3.2.10.2.3.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
msbj – the Jacobian recomputation or preconditioner update frequency.
 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 Jacobian update frequency is only checked within calls to the linear solver setup routine, as such values of msbj \(<\) msbp will result in recomputing the Jacobian every msbp steps. See
ARKStepSetLSetupFrequency()
for setting the linear solver steup frequency msbp.Passing a value msbj \(\le 0\) indicates to use the default value of 51.
This function must be called after the ARKLS system solver interface has been initialized through a call to
ARKStepSetLinearSolver()
.
3.4.2.2.8.5.2. Optional inputs for matrixbased SUNLinearSolver
modules
Optional input 
Function name 
Default 

Jacobian function 


Linear system function 
internal 

Mass matrix function 
none 

Enable or disable linear solution scaling 
on 
When using matrixbased linear solver modules, the ARKLS solver interface needs a function to compute an approximation to the Jacobian matrix \(J(t,y)\) or the linear system \(\mathcal{A}(t,y) = M(t)  \gamma J(t,y)\).
For \(J(t,y)\), the ARKLS interface is packaged with a routine that can approximate
\(J\) if the user has selected either the SUNMATRIX_DENSE or
SUNMATRIX_BAND objects. Alternatively,
the user can supply a custom Jacobian function of type ARKLsJacFn()
– this is
required when the user selects other matrix formats. To specify a usersupplied
Jacobian function, ARKStep provides the function ARKStepSetJacFn()
.
Alternatively, a function of type ARKLsLinSysFn()
can be provided to
evaluate the matrix \(\mathcal{A}(t,y)\). By default, ARKLS uses an
internal linear system function leveraging the SUNMATRIX API to form the matrix
\(\mathcal{A}(t,y)\) by combining the matrices \(M(t)\) and \(J(t,y)\).
To specify a usersupplied linear system function instead, ARKStep provides the function
ARKStepSetLinSysFn()
.
If the ODE system involves a nonidentity mass matrix, \(M\ne I\), matrixbased linear
solver modules require a function to compute an approximation to the mass matrix \(M(t)\).
There is no default difference quotient approximation (for any matrix type), so this
routine must be supplied by the user. This function must be of type
ARKLsMassFn()
, and should be set using the function
ARKStepSetMassFn()
.
In either case (\(J(t,y)\) versus \(\mathcal{A}(t,y)\) is supplied) the matrix
information will be updated infrequently to reduce matrix construction and, with direct
solvers, factorization costs. As a result the value of \(\gamma\) may not be current
and a scaling factor is applied to the solution of the linear system to account for
the lagged value of \(\gamma\). See §11.2.1 for more details.
The function ARKStepSetLinearSolutionScaling()
can be used to disable this
scaling when necessary, e.g., when providing a custom linear solver that updates the
matrix using the current \(\gamma\) as part of the solve.
The ARKLS interface passes the user data pointer to the Jacobian, linear
system, and mass matrix functions. This allows the user to create an arbitrary
structure with relevant problem data and access it during the execution of the
usersupplied Jacobian, linear system or mass matrix functions, without using global
data in the program. The user data pointer may be specified through
ARKStepSetUserData()
.

int ARKStepSetJacFn(void *arkode_mem, ARKLsJacFn jac)
Specifies the Jacobian approximation routine to be used for the matrixbased solver with the ARKLS interface.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
jac – name of usersupplied Jacobian approximation 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:
This routine must be called after the ARKLS linear solver interface has been initialized through a call to
ARKStepSetLinearSolver()
.By default, ARKLS uses an internal difference quotient function for the SUNMATRIX_DENSE and SUNMATRIX_BAND modules. If
NULL
is passed in for jac, this default is used. An error will occur if no jac is supplied when using other matrix types.The function type
ARKLsJacFn()
is described in §3.4.5.

int ARKStepSetLinSysFn(void *arkode_mem, ARKLsLinSysFn linsys)
Specifies the linear system approximation routine to be used for the matrixbased solver with the ARKLS interface.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
linsys – name of usersupplied linear system approximation 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:
This routine must be called after the ARKLS linear solver interface has been initialized through a call to
ARKStepSetLinearSolver()
.By default, ARKLS uses an internal linear system function that leverages the SUNMATRIX API to form the system \(M  \gamma J\). If
NULL
is passed in for linsys, this default is used.The function type
ARKLsLinSysFn()
is described in §3.4.5.

int ARKStepSetMassFn(void *arkode_mem, ARKLsMassFn mass)
Specifies the mass matrix approximation routine to be used for the matrixbased solver with the ARKLS interface.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
mass – name of usersupplied mass matrix approximation function.
 Return value:
ARKLS_SUCCESS if successful
ARKLS_MEM_NULL if the ARKStep memory was
NULL
ARKLS_MASSMEM_NULL if the mass matrix solver memory was
NULL
ARKLS_ILL_INPUT if an argument has an illegal value
 Notes:
This routine must be called after the ARKLS mass matrix solver interface has been initialized through a call to
ARKStepSetMassLinearSolver()
.Since there is no default difference quotient function for mass matrices, mass must be non
NULL
.The function type
ARKLsMassFn()
is described in §3.4.5.

int ARKStepSetLinearSolutionScaling(void *arkode_mem, booleantype onoff)
Enables or disables scaling the linear system solution to account for a change in \(\gamma\) in the linear system. For more details see §11.2.1.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
onoff – flag to enable (
SUNTRUE
) or disable (SUNFALSE
) scaling
 Return value:
ARKLS_SUCCESS if successful
ARKLS_MEM_NULL if the ARKStep memory was
NULL
ARKLS_ILL_INPUT if the attached linear solver is not matrixbased
 Notes:
Linear solution scaling is enabled by default when a matrixbased linear solver is attached.
3.4.2.2.8.5.3. Optional inputs for matrixfree SUNLinearSolver
modules
Optional input 
Function name 
Default 

\(Jv\) functions (jtimes and jtsetup) 
DQ, none 

\(Jv\) DQ rhs function (jtimesRhsFn) 
fi 

\(Mv\) functions (mtimes and mtsetup) 
none, none 
As described in §3.2.10.2, when solving the Newton linear systems with matrixfree methods, the ARKLS interface requires a jtimes function to compute an approximation to the product between the Jacobian matrix \(J(t,y)\) and a vector \(v\). The user can supply a custom Jacobiantimesvector approximation function, or use the default internal difference quotient function that comes with the ARKLS interface.
A userdefined Jacobianvector function must be of type
ARKLsJacTimesVecFn
and can be specified through a call
to ARKStepSetJacTimes()
(see §3.4.5
for specification details). As with the
usersupplied preconditioner functions, the evaluation and
processing of any Jacobianrelated data needed by the user’s
Jacobiantimesvector function is done in the optional usersupplied
function of type ARKLsJacTimesSetupFn
(see
§3.4.5 for specification details). As with
the preconditioner functions, a pointer to the userdefined
data structure, user_data, specified through
ARKStepSetUserData()
(or a NULL
pointer otherwise) is
passed to the Jacobiantimesvector setup and product functions each
time they are called.

int ARKStepSetJacTimes(void *arkode_mem, ARKLsJacTimesSetupFn jtsetup, ARKLsJacTimesVecFn jtimes)
Specifies the Jacobiantimesvector setup and product functions.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
jtsetup – userdefined Jacobianvector setup function. Pass
NULL
if no setup is necessary.jtimes – userdefined Jacobianvector product 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
.ARKLS_ILL_INPUT if an input has an illegal value.
ARKLS_SUNLS_FAIL if an error occurred when setting up the Jacobianvector product in the
SUNLinearSolver
object used by the ARKLS interface.
 Notes:
The default is to use an internal finite difference quotient for jtimes and to leave out jtsetup. If
NULL
is passed to jtimes, these defaults are used. A user may specify nonNULL
jtimes andNULL
jtsetup inputs.This function must be called after the ARKLS system solver interface has been initialized through a call to
ARKStepSetLinearSolver()
.The function types
ARKLsJacTimesSetupFn
andARKLsJacTimesVecFn
are described in §3.4.5.
When using the internal difference quotient the user may optionally supply
an alternative implicit righthand side function for use in the Jacobianvector
product approximation by calling ARKStepSetJacTimesRhsFn()
. The
alternative implicit righthand side function should compute a suitable (and
differentiable) approximation to the \(f^I\) function provided to
ARKStepCreate()
. For example, as done in [44],
the alternative function may use lagged values when evaluating a nonlinearity
in \(f^I\) to avoid differencing a potentially nondifferentiable factor.
We note that in many instances this same \(f^I\) routine would also have
been desirable for the nonlinear solver, in which case the user should specify
this through calls to both ARKStepSetJacTimesRhsFn()
and
ARKStepSetNlsRhsFn()
.

int ARKStepSetJacTimesRhsFn(void *arkode_mem, ARKRhsFn jtimesRhsFn)
Specifies an alternative implicit righthand side function for use in the internal Jacobianvector product difference quotient approximation.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
jtimesRhsFn – the name of the C function (of type
ARKRhsFn()
) defining the alternative 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
.ARKLS_ILL_INPUT if an input has an illegal value.
 Notes:
The default is to use the implicit righthand side function provided to
ARKStepCreate()
in the internal difference quotient. If the input implicit righthand side function isNULL
, the default is used.This function must be called after the ARKLS system solver interface has been initialized through a call to
ARKStepSetLinearSolver()
.
Similarly, if a problem involves a nonidentity mass matrix,
\(M\ne I\), then matrixfree solvers require a mtimes function
to compute an approximation to the product between the mass matrix
\(M(t)\) and a vector \(v\). This function must be
usersupplied since there is no default value, it must be
of type ARKLsMassTimesVecFn()
, and can be specified
through a call to the ARKStepSetMassTimes()
routine.
Similarly to the usersupplied preconditioner functions, any evaluation
and processing of any mass matrixrelated data needed by the user’s
massmatrixtimesvector function may be done in an optional usersupplied
function of type ARKLsMassTimesSetupFn
(see
§3.4.5 for specification details).

int ARKStepSetMassTimes(void *arkode_mem, ARKLsMassTimesSetupFn mtsetup, ARKLsMassTimesVecFn mtimes, void *mtimes_data)
Specifies the mass matrixtimesvector setup and product functions.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
mtsetup – userdefined mass matrixvector setup function. Pass
NULL
if no setup is necessary.mtimes – userdefined mass matrixvector product function.
mtimes_data – a pointer to user data, that will be supplied to both the mtsetup and mtimes functions.
 Return value:
ARKLS_SUCCESS if successful.
ARKLS_MEM_NULL if the ARKStep memory was
NULL
.ARKLS_MASSMEM_NULL if the mass matrix solver memory was
NULL
.ARKLS_ILL_INPUT if an input has an illegal value.
ARKLS_SUNLS_FAIL if an error occurred when setting up the massmatrixvector product in the
SUNLinearSolver
object used by the ARKLS interface.
 Notes:
There is no default finite difference quotient for mtimes, so if using the ARKLS mass matrix solver interface with NULLvalued SUNMATRIX input \(M\), and this routine is called with NULLvalued mtimes, an error will occur. A user may specify
NULL
for mtsetup.This function must be called after the ARKLS mass matrix solver interface has been initialized through a call to
ARKStepSetMassLinearSolver()
.The function types
ARKLsMassTimesSetupFn
andARKLsMassTimesVecFn
are described in §3.4.5.
3.4.2.2.8.5.4. Optional inputs for iterative SUNLinearSolver
modules
Optional input 
Function name 
Default 

Newton preconditioning functions 


Mass matrix preconditioning functions 


Newton linear and nonlinear tolerance ratio 
0.05 

Mass matrix linear and nonlinear tolerance ratio 
0.05 

Newton linear solve tolerance conversion factor 
vector length 

Mass matrix linear solve tolerance conversion factor 
vector length 
As described in §3.2.10.2, when using
an iterative linear solver the user may supply a preconditioning
operator to aid in solution of the system. This operator consists of
two usersupplied functions, psetup and psolve, that are supplied
to ARKStep using either the function
ARKStepSetPreconditioner()
(for preconditioning the
Newton system), or the function
ARKStepSetMassPreconditioner()
(for preconditioning the
mass matrix system). The psetup function supplied to these routines
should handle evaluation and preprocessing of any Jacobian or
massmatrix data needed by the user’s preconditioner solve function,
psolve. The user data pointer received through
ARKStepSetUserData()
(or a pointer to NULL
if user data
was not specified) is passed to the psetup and psolve functions.
This allows the user to create an arbitrary
structure with relevant problem data and access it during the
execution of the usersupplied preconditioner functions without using
global data in the program. If preconditioning is supplied for both
the Newton and mass matrix linear systems, it is expected that the
user will supply different psetup and psolve function for each.
Also, as described in §3.2.10.3.2, the ARKLS interface requires that iterative linear solvers stop when the norm of the preconditioned residual satisfies
where the default \(\epsilon_L = 0.05\) may be modified by
the user through the ARKStepSetEpsLin()
function.

int ARKStepSetPreconditioner(void *arkode_mem, ARKLsPrecSetupFn psetup, ARKLsPrecSolveFn psolve)
Specifies the usersupplied preconditioner setup and solve functions.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
psetup – user defined preconditioner setup function. Pass
NULL
if no setup is needed.psolve – userdefined preconditioner solve 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
.ARKLS_ILL_INPUT if an input has an illegal value.
ARKLS_SUNLS_FAIL if an error occurred when setting up preconditioning in the
SUNLinearSolver
object used by the ARKLS interface.
 Notes:
The default is
NULL
for both arguments (i.e., no preconditioning).This function must be called after the ARKLS system solver interface has been initialized through a call to
ARKStepSetLinearSolver()
.Both of the function types
ARKLsPrecSetupFn()
andARKLsPrecSolveFn()
are described in §3.4.5.

int ARKStepSetMassPreconditioner(void *arkode_mem, ARKLsMassPrecSetupFn psetup, ARKLsMassPrecSolveFn psolve)
Specifies the mass matrix preconditioner setup and solve functions.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
psetup – user defined preconditioner setup function. Pass
NULL
if no setup is to be done.psolve – userdefined preconditioner solve 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
.ARKLS_ILL_INPUT if an input has an illegal value.
ARKLS_SUNLS_FAIL if an error occurred when setting up preconditioning in the
SUNLinearSolver
object used by the ARKLS interface.
 Notes:
This function must be called after the ARKLS mass matrix solver interface has been initialized through a call to
ARKStepSetMassLinearSolver()
.The default is
NULL
for both arguments (i.e. no preconditioning).Both of the function types
ARKLsMassPrecSetupFn()
andARKLsMassPrecSolveFn()
are described in §3.4.5.

int ARKStepSetEpsLin(void *arkode_mem, realtype eplifac)
Specifies the factor \(\epsilon_L\) by which the tolerance on the nonlinear iteration is multiplied to get a tolerance on the linear iteration.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
eplifac – linear convergence safety factor.
 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
.ARKLS_ILL_INPUT if an input has an illegal value.
 Notes:
Passing a value eplifac \(\le 0\) indicates to use the default value of 0.05.
This function must be called after the ARKLS system solver interface has been initialized through a call to
ARKStepSetLinearSolver()
.

int ARKStepSetMassEpsLin(void *arkode_mem, realtype eplifac)
Specifies the factor by which the tolerance on the nonlinear iteration is multiplied to get a tolerance on the mass matrix linear iteration.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
eplifac – linear convergence safety factor.
 Return value:
ARKLS_SUCCESS if successful.
ARKLS_MEM_NULL if the ARKStep memory was
NULL
.ARKLS_MASSMEM_NULL if the mass matrix solver memory was
NULL
.ARKLS_ILL_INPUT if an input has an illegal value.
 Notes:
This function must be called after the ARKLS mass matrix solver interface has been initialized through a call to
ARKStepSetMassLinearSolver()
.Passing a value eplifac \(\le 0\) indicates to use the default value of 0.05.
Since iterative linear solver libraries typically consider linear residual tolerances using the \(L_2\) norm, whereas ARKODE focuses on errors measured in the WRMS norm (3.17), the ARKLS interface internally converts between these quantities when interfacing with linear solvers,
Prior to the introduction of N_VGetLength()
in SUNDIALS v5.0.0 the
value of \(nrmfac\) was computed using the vector dot product. Now, the
functions ARKStepSetLSNormFactor()
and ARKStepSetMassLSNormFactor()
allow for additional user control over these conversion factors.

int ARKStepSetLSNormFactor(void *arkode_mem, realtype nrmfac)
Specifies the factor to use when converting from the integrator tolerance (WRMS norm) to the linear solver tolerance (L2 norm) for Newton linear system solves.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
nrmfac – the norm conversion factor. If nrmfac is:
\(> 0\) then the provided value is used.
\(= 0\) then the conversion factor is computed using the vector length i.e.,
nrmfac = sqrt(N_VGetLength(y))
(default).\(< 0\) then the conversion factor is computed using the vector dot product i.e.,
nrmfac = sqrt(N_VDotProd(v,v))
where all the entries ofv
are one.
 Return value:
ARK_SUCCESS if successful.
ARK_MEM_NULL if the ARKStep memory was
NULL
.
 Notes:
This function must be called after the ARKLS system solver interface has been initialized through a call to
ARKStepSetLinearSolver()
.

int ARKStepSetMassLSNormFactor(void *arkode_mem, realtype nrmfac)
Specifies the factor to use when converting from the integrator tolerance (WRMS norm) to the linear solver tolerance (L2 norm) for mass matrix linear system solves.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
nrmfac – the norm conversion factor. If nrmfac is:
\(> 0\) then the provided value is used.
\(= 0\) then the conversion factor is computed using the vector length i.e.,
nrmfac = sqrt(N_VGetLength(y))
(default).\(< 0\) then the conversion factor is computed using the vector dot product i.e.,
nrmfac = sqrt(N_VDotProd(v,v))
where all the entries ofv
are one.
 Return value:
ARK_SUCCESS if successful.
ARK_MEM_NULL if the ARKStep memory was
NULL
.
 Notes:
This function must be called after the ARKLS mass matrix solver interface has been initialized through a call to
ARKStepSetMassLinearSolver()
.
3.4.2.2.8.6. 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.11.
Optional input 
Function name 
Default 

Direction of zerocrossings to monitor 
both 

Disable inactive root warnings 
enabled 

int ARKStepSetRootDirection(void *arkode_mem, int *rootdir)
Specifies the direction of zerocrossings to be located and returned.
 Arguments:
arkode_mem – pointer to the ARKStep 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
ARKStepRootInit()
). 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 zerocrossings where \(g_i\) is increasing or decreasing, respectively.
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
ARK_ILL_INPUT if an argument has an illegal value
 Notes:
The default behavior is to monitor for both zerocrossing directions.

int ARKStepSetNoInactiveRootWarn(void *arkode_mem)
Disables issuing a warning if some root function appears to be identically zero at the beginning of the integration.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is
NULL
 Notes:
ARKStep will not report the initial conditions as a possible zerocrossing (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), ARKStep will issue a warning which can be disabled with this optional input function.
3.4.2.2.9. 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” or
“continuous extension” algorithm is identical to the algorithm used for
the maximum order implicit predictors, described in
§3.2.10.5.2, 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. \(y^{(k)}(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 min(degree, 5), where degree is the argument provided to
ARKStepSetInterpolantDegree()
. 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. 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,…, min(degree, kmax)}.
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()
andARKStepGetLastStep()
, respectively.
3.4.2.2.10. Optional output functions
ARKStep provides an extensive set of functions that can be used to obtain solver performance information. We organize these into groups:
General ARKStep output routines are in §3.4.2.2.10.1,
ARKStep implicit solver output routines are in §3.4.2.2.10.2,
Output routines regarding rootfinding results are in §3.4.2.2.10.3,
Linear solver output routines are in §3.4.2.2.10.4 and
General usability routines (e.g. to print the current ARKStep parameters, or output the current Butcher table(s)) are in §3.4.2.2.10.5.
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 and nfi_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 (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, and hence a lower ratio.
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.
3.4.2.2.10.1. Main solver optional output functions
Optional output 
Function name 

Size of ARKStep real and integer workspaces 

Cumulative number of internal steps 

Actual initial time step size used 

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 solution reached by the solver 

Current \(\gamma\) value used by the solver 

Suggested factor for tolerance scaling 

Error weight vector for state variables 

Residual weight vector 

Single accessor to many statistics at once 

Print all statistics 

Name of constant associated with a return flag 

No. of explicit stabilitylimited steps 

No. of accuracylimited steps 

No. of attempted steps 

No. of calls to fe and fi functions 

No. of local error test failures that have occurred 

No. of failed steps due to a nonlinear solver failure 

Current ERK and DIRK Butcher tables 

Estimated local truncation error vector 

Single accessor to many statistics at once 

Number of constraint test failures 

Retrieve a pointer for user data 

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 ARKStepGetCurrentState(void *arkode_mem, N_Vector *ycur)
Returns the current internal solution reached by the solver.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
ycur – current internal solution.
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory was
NULL
 Notes:
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 ARKStepGetCurrentGamma(void *arkode_mem, realtype *gamma)
Returns the current internal value of \(\gamma\) used in the implicit solver Newton matrix (see equation (3.32)).
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
gamma – current step size scaling factor in the Newton system.
 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

int ARKStepPrintAllStats(void *arkode_mem, FILE *outfile, SUNOutputFormat fmt)
Outputs all of the integrator, nonlinear solver, linear solver, and other statistics.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
outfile – pointer to output file.
fmt – the output format:
SUN_OUTPUTFORMAT_TABLE
– prints a table of valuesSUN_OUTPUTFORMAT_CSV
– prints a commaseparated list of key and value pairs e.g.,key1,value1,key2,value2,...
 Return value:
ARK_SUCCESS – if the output was successfully.
ARK_MEM_NULL – if the ARKStep 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.New in version 5.2.0.

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 ARKStepGetNumStepSolveFails(void *arkode_mem, long int *ncnf)
Returns the number of failed steps due to a nonlinear solver failure (so far).
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
ncnf – number of step failures.
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory was
NULL

int ARKStepGetCurrentButcherTables(void *arkode_mem, ARKodeButcherTable *Bi, ARKodeButcherTable *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 the implicit Butcher table structure.
Be – pointer to the explicit Butcher table structure.
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory was
NULL
Note: 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 §3.5.

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 aseweight[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

int ARKStepGetNumConstrFails(void *arkode_mem, long int *nconstrfails)
Returns the cumulative number of constraint test failures (so far).
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
nconstrfails – number of constraint test failures.
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory was
NULL

int ARKStepGetUserData(void *arkode_mem, void **user_data)
Returns the user data pointer previously set with
ARKStepSetUserData()
. Arguments:
arkode_mem – pointer to the ARKStep memory block.
user_data – memory reference to a user data pointer
 Return value:
ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory was
NULL
New in version 5.3.0.
3.4.2.2.10.2. Implicit solver optional output functions
Optional output 
Function name 

No. of calls to linear solver setup function 

No. of nonlinear solver iterations 

No. of nonlinear solver convergence failures 

Single accessor to all nonlinear solver statistics 

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
Note: 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
Note: 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
Note: 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
Note: This is 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.
3.4.2.2.10.3. Rootfinding optional output functions
Optional output 
Function name 

Array showing roots found 

No. of calls to user root function 

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
3.4.2.2.10.4. Linear solver interface optional output functions
A variety of optional outputs are available from the ARKLS interface, as listed in the following table and elaborated below. We 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).
Optional output 
Function name 

Stored Jacobian of the ODE RHS function 

Time at which the Jacobian was evaluated 

Step number at which the Jacobian was evaluated 

Size of real and integer workspaces 

No. of Jacobian evaluations 

No. of preconditioner evaluations 

No. of preconditioner solves 

No. of linear iterations 

No. of linear convergence failures 

No. of Jacobianvector setup evaluations 

No. of Jacobianvector product evaluations 

No. of fi calls for finite diff. \(J\) or \(Jv\) evals. 

Last return from a linear solver function 

Name of constant associated with a return flag 

Size of real and integer mass matrix solver workspaces 

No. of mass matrix solver setups (incl. \(M\) evals.) 

No. of mass matrix multiply setups 

No. of mass matrix multiplies 

No. of mass matrix solves 

No. of mass matrix preconditioner evaluations 

No. of mass matrix preconditioner solves 

No. of mass matrix linear iterations 

No. of mass matrix solver convergence failures 

No. of massmatrixvector setup evaluations 

Last return from a mass matrix solver function 

int ARKStepGetJac(void *arkode_mem, SUNMatrix *J)
Returns the internally stored copy of the Jacobian matrix of the ODE implicit righthand side function.
 Parameters
arkode_mem – the ARKStep memory structure
J – the Jacobian matrix
 Return values
ARKLS_SUCCESS – the output value has been successfully set
ARKLS_MEM_NULL –
arkode_mem
wasNULL
ARKLS_LMEM_NULL – the linear solver interface has not been initialized
Warning
This function is provided for debugging purposes and the values in the returned matrix should not be altered.

int ARKStepGetJacTime(void *arkode_mem, sunrealtype *t_J)
Returns the time at which the internally stored copy of the Jacobian matrix of the ODE implicit righthand side function was evaluated.
 Parameters
arkode_mem – the ARKStep memory structure
t_J – the time at which the Jacobian was evaluated
 Return values
ARKLS_SUCCESS – the output value has been successfully set
ARKLS_MEM_NULL –
arkode_mem
wasNULL
ARKLS_LMEM_NULL – the linear solver interface has not been initialized

int ARKStepGetJacNumSteps(void *arkode_mem, long int *nst_J)
Returns the value of the internal step counter at which the internally stored copy of the Jacobian matrix of the ODE implicit righthand side function was evaluated.
 Parameters
arkode_mem – the ARKStep memory structure
nst_J – the value of the internal step counter at which the Jacobian was evaluated
 Return values
ARKLS_SUCCESS – the output value has been successfully set
ARKLS_MEM_NULL –
arkode_mem
wasNULL
ARKLS_LMEM_NULL – the linear solver interface has not been initialized

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 Jacobian evaluations.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
njevals – number of Jacobian evaluations.
 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
Note: 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 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
and that returned*jcurPtr
=SUNTRUE
. 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
Note: 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 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
Note: 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 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
Note: 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
Note: 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 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
Note: 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 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
Note: 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 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.
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 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
orSUNLINSOL_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 theSUNLinearSolver
object, which will be one of: SUNLS_MEM_NULL, indicating that theSUNLinearSolver
memory isNULL
; SUNLS_ATIMES_NULL, indicating that a matrixfree iterative solver was provided, but is missing a routine for the matrixvector product approximation, SUNLS_ATIMES_FAIL_UNREC, indicating an unrecoverable failure in the \(Jv\) function; SUNLS_PSOLVE_NULL, indicating that an iterative linear solver was configured to use preconditioning, but no preconditioner solve routine was provided, 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
orSUNLINSOL_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
Note: This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new massmatrix linear solver module is “attached” to ARKStep, or when ARKStep is resized.

int ARKStepGetNumMassMultSetups(void *arkode_mem, long int *nmvsetups)
Returns the number of calls made to the ARKLS mass matrix ‘matvec setup’ (matrixbased solvers) routine.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
nmvsetups – number of calls to the mass matrix matrixtimesvector 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
Note: This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new massmatrix linear solver module is “attached” to ARKStep, or when ARKStep is resized.

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
Note: This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new massmatrix linear solver module is “attached” to ARKStep, or when ARKStep is resized.

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
Note: This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new massmatrix linear solver module is “attached” to ARKStep, or when ARKStep is resized.

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
Note: This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new massmatrix linear solver module is “attached” to ARKStep, or when ARKStep is resized.

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
Note: This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new massmatrix linear solver module is “attached” to ARKStep, or when ARKStep is resized.

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
Note: This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new massmatrix linear solver module is “attached” to ARKStep, or when ARKStep is resized.

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
Note: This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new massmatrix linear solver module is “attached” to ARKStep, or when ARKStep is resized.

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
Note: This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new massmatrix linear solver module is “attached” to ARKStep, or when ARKStep is resized.

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()
.
3.4.2.2.10.5. General usability functions
The following optional routines may be called by a user to inquire about existing solver parameters or write the current Butcher table(s). While neither of these would typically be called during the course of solving an initial value problem, they may be useful for users wishing to better understand ARKStep and/or specific Runge–Kutta methods.
Optional routine 
Function name 

Output all ARKStep solver parameters 

Output the current Butcher table(s) 

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
orstderr
, or it may point to a specific file created usingfopen
.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
orstderr
, or it may point to a specific file created usingfopen
.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.
3.4.2.2.11. ARKStep reinitialization function
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
retains the current settings for all ARKstep module options and
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, and deletes any previouslyset tstop value specified via a
call to ARKStepSetStopTime()
. 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 §3.4.2.2.3. 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:
All previously set options are retained but may be updated by calling the appropriate “Set” functions.
If an error occurred,
ARKStepReInit()
also sends an error message to the error handler function.
3.4.2.2.12. ARKStep reset function
To reset the ARKStep module to a particular state \((t_R,y(t_R))\) for the
continued solution of a problem, where a prior
call to ARKStepCreate()
has been made, the user must call the function
ARKStepReset()
. Like ARKStepReInit()
this routine retains
the current settings for all ARKStep module options and performs no memory
allocations but, unlike ARKStepReInit()
, this routine performs only a
subset of the input checking and initializations that are done in
ARKStepCreate()
. In particular this routine retains all internal
counter values and the step size/error history and does not reinitialize the
linear and/or nonlinear solver but it does indicate that a linear solver setup
is necessary in the next step. Like ARKStepReInit()
, a call to
ARKStepReset()
will delete any previouslyset tstop value specified
via a call to ARKStepSetStopTime()
. Following a successful call to
ARKStepReset()
, call ARKStepEvolve()
again to continue
solving the problem. By default the next call to ARKStepEvolve()
will
use the step size computed by ARKStep prior to calling ARKStepReset()
.
To set a different step size or have ARKStep estimate a new step size use
ARKStepSetInitStep()
.
One important use of the ARKStepReset()
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 ARKStepReset()
. 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 ARKStepReset(void *arkode_mem, realtype tR, N_Vector yR)
Resets the current ARKStep timestepper module state to the provided independent variable value and dependent variable vector.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
tR – the value of the independent variable \(t\).
yR – the value of the dependent variable vector \(y(t_R)\).
 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:
By default the next call to
ARKStepEvolve()
will use the step size computed by ARKStep prior to callingARKStepReset()
. To set a different step size or have ARKStep estimate a new step size useARKStepSetInitStep()
.All previously set options are retained but may be updated by calling the appropriate “Set” functions.
If an error occurred,
ARKStepReset()
also sends an error message to the error handler function.
3.4.2.2.13. 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 yR, realtype hscale, realtype tR, ARKVecResizeFn resize, void *resize_data)
Resizes ARKStep with a different state vector but with comparable dynamical time scale.
 Arguments:
arkode_mem – pointer to the ARKStep memory block.
yR – the newlysized state vector, holding the current dependent variable values \(y(t_R)\).
hscale – the desired time step scaling factor (i.e. the next step will be of size h*hscale).
tR – the current value of the independent variable \(t_R\) (this must be consistent with yR).
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.If inequality constraint checking is enabled a call to
ARKStepResize()
will disable constraint checking. A call toARKStepSetConstraints()
is required to reenable constraint checking. 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 updatedSUNLinearSolver
(and possiblySUNMatrix
) object(s) through calls toARKStepSetLinearSolver()
, andARKStepSetMassLinearSolver()
.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 toARKStepResize()
through a new call toARKStepSVtolerances()
and possiblyARKStepResVtolerance()
if applicable.If scalarvalued tolerances or a tolerance function was specified through either
ARKStepSStolerances()
orARKStepWFtolerances()
, then these will remain valid and no further action is necessary. Example codes:
examples/arkode/C_serial/ark_heat1D_adapt.c
3.4.2.2.14. Interfacing with MRIStep
When using ARKStep as the inner (fast) integrator with MRIStep, the
utility function ARKStepCreateMRIStepInnerStepper()
should be used to
wrap an ARKStep memory block as an MRIStepInnerStepper
.

int ARKStepCreateMRIStepInnerStepper(void *inner_arkode_mem, MRIStepInnerStepper *stepper)
Wraps an ARKStep memory block as an
MRIStepInnerStepper
for use with MRIStep. Arguments:
arkode_mem – pointer to the ARKStep memory block.
stepper – the
MRIStepInnerStepper
object.
 Return value:
ARK_SUCCESS if successful
ARK_MEM_FAIL if a memory allocation failed
ARK_ILL_INPUT if an argument has an illegal value.
 Example usage:
/* fast (inner) and slow (outer) ARKODE objects */ void *inner_arkode_mem = NULL; void *outer_arkode_mem = NULL; /* MRIStepInnerStepper to wrap the inner (fast) ARKStep object */ MRIStepInnerStepper stepper = NULL; /* create an ARKStep object, setting fast (inner) righthand side functions and the initial condition */ inner_arkode_mem = ARKStepCreate(ffe, ffi, t0, y0, sunctx); /* setup ARKStep */ . . . /* create MRIStepInnerStepper wrapper for the ARKStep memory block */ flag = ARKStepCreateMRIStepInnerStepper(inner_arkode_mem, &stepper); /* create an MRIStep object, setting the slow (outer) righthand side functions and the initial condition */ outer_arkode_mem = MRIStepCreate(fse, fsi, t0, y0, stepper, sunctx)
 Example codes:
examples/arkode/CXX_parallel/ark_diffusion_reaction_p.cpp