2.4.3. ARKODE User-callable functions
This section describes the shared ARKODE functions that are called by the user to setup and then solve an IVP. Some of these are required; however, starting with §2.4.3.8, the functions listed involve optional inputs/outputs or restarting, and those paragraphs may be skipped for a casual use of ARKODE. In any case, refer to the preceding section, §2.4.2, for the correct order of these calls.
On an error, each user-callable function returns a negative value (or
NULL
if the function returns a pointer) and sends an error message
to the error handler, which prints the message to stderr
by default.
However, the user can set a file as error output or can
provide their own error handler (see §1.5 for details).
We note that depending on the choice of time-stepping module, only a subset of ARKODE’s user-callable functions will be applicable/supported. We thus categorize the functions below into five groups:
functions that apply for all time-stepping modules,
functions that apply for time-stepping modules that allow temporal adaptivity,
functions that apply for time-stepping modules that utilize implicit solvers (nonlinear or linear),
functions that apply for time-stepping modules that support non-identity mass matrices, and
functions that apply for time-stepping modules that support relaxation Runge–Kutta methods.
In the function descriptions below, we identify those that have any of the restrictions B-E above. Then in the introduction for each of the stepper-specific documentation sections (§2.4.7.1, §2.4.8.1, §2.4.9.1, §2.4.10.1, §2.4.11.2, §2.4.12.2, and §2.4.13.1) we clarify the categories of these functions that are supported.
2.4.3.1. ARKODE initialization and deallocation functions
For functions to create an ARKODE stepper instance see ARKStepCreate()
,
ERKStepCreate()
, ForcingStepCreate()
,
LSRKStepCreateSTS()
, LSRKStepCreateSSP()
,
MRIStepCreate()
, SplittingStepCreate()
, or
SPRKStepCreate()
.
-
void ARKodeFree(void **arkode_mem)
This function frees the problem memory created a stepper constructor.
- Parameters:
arkode_mem – pointer to the ARKODE stepper memory block.
- Returns:
none
Added in version 6.1.0: This function replaces stepper specific versions in ARKStep, ERKStep, MRIStep, and SPRKStep.
2.4.3.2. ARKODE tolerance specification functions
These functions specify the integration tolerances. One of them
should be called before the first call to
ARKodeEvolve()
; otherwise default values of reltol =
1e-4
and abstol = 1e-9
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
ARKodeSStolerances()
, this vector has components
ewt[i] = 1.0/(reltol*abs(y[i]) + abstol);
whereas in the case of ARKodeSVtolerances()
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 error-like 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 ARKodeWFtolerances()
.
-
int ARKodeSStolerances(void *arkode_mem, sunrealtype reltol, sunrealtype abstol)
This function specifies scalar relative and absolute tolerances.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
reltol – scalar relative tolerance.
abstol – scalar absolute tolerance.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_NO_MALLOC –
arkode_mem
was not allocated.ARK_ILL_INPUT – an argument had an illegal value (e.g. a negative tolerance).
Added in version 6.1.0.
-
int ARKodeSVtolerances(void *arkode_mem, sunrealtype 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).
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
reltol – scalar relative tolerance.
abstol – vector containing the absolute tolerances for each solution component.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_NO_MALLOC –
arkode_mem
was not allocated.ARK_ILL_INPUT – an argument had an illegal value (e.g. a negative tolerance).
Added in version 6.1.0.
-
int ARKodeWFtolerances(void *arkode_mem, ARKEwtFn efun)
This function specifies a user-supplied function efun to compute the error weight vector
ewt
.- Parameters:
arkode_mem – pointer to the ARKODE memory block.
efun – the name of the function (of type
ARKEwtFn()
) that implements the error weight vector computation.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_NO_MALLOC –
arkode_mem
was not allocated.
Added in version 6.1.0.
Moreover, for problems involving a non-identity 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, ARKODE defines a vector of residual
weights, rwt
for measuring convergence of these iterative solvers.
In the case of ARKodeResStolerance()
, this vector has components
rwt[i] = 1.0/(reltol*abs(My[i]) + rabstol);
whereas in the case of ARKodeResVtolerance()
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 residual-like 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
ARKodeResFtolerance()
. Further information on all three of
these functions is provided below.
-
int ARKodeResStolerance(void *arkode_mem, sunrealtype rabstol)
This function specifies a scalar absolute residual tolerance.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
rabstol – scalar absolute residual tolerance.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_NO_MALLOC –
arkode_mem
was not allocated.ARK_ILL_INPUT – an argument had an illegal value (e.g. a negative tolerance).
Added in version 6.1.0.
-
int ARKodeResVtolerance(void *arkode_mem, N_Vector rabstol)
This function specifies a vector of absolute residual tolerances.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
rabstol – vector containing the absolute residual tolerances for each solution component.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_NO_MALLOC –
arkode_mem
was not allocated.ARK_ILL_INPUT – an argument had an illegal value (e.g. a negative tolerance).
Added in version 6.1.0.
-
int ARKodeResFtolerance(void *arkode_mem, ARKRwtFn rfun)
This function specifies a user-supplied function rfun to compute the residual weight vector
rwt
.- Parameters:
arkode_mem – pointer to the ARKODE memory block.
rfun – the name of the function (of type
ARKRwtFn()
) that implements the residual weight vector computation.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_NO_MALLOC –
arkode_mem
was not allocated.
Added in version 6.1.0.
2.4.3.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 double-precision).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 [110]. 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 problem-dependent. 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 already-suppliedabstol
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 per-step errors, where that accumulation factor is problem-dependent. 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.
2.4.3.2.2. Advice on controlling nonphysical negative values
In many applications, some components in the true solution are always positive or non-negative, 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 ARKODE, with magnitude comparable to
abstol
or less, is equivalent to zero as far as the computation is concerned.The user’s right-hand side routines \(f^E\) and \(f^I\) should never change a negative value in the solution vector \(y\) to a non-negative 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)\).
Some of ARKODE’s time stepping modules support component-wise constraints on solution components, \(y_i < 0\), \(y_i \le 0\), \(y_i > 0\), or \(y_i \ge 0\), through the user-callable function
ARKodeSetConstraints()
. At each internal time step, if any constraint is violated then ARKODE 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.For time-stepping modules that support temporal adaptivity, positivity and non-negativity constraints on components can also be enforced by use of the recoverable error return feature in the user-supplied right-hand side function(s). When a recoverable error is encountered, ARKODE 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.
2.4.3.3. Linear solver interface functions
As previously explained, the Newton iterations used in solving implicit systems within ARKODE require the solution of linear systems of the form
where
ARKODE’s ARKLS linear solver interface supports all valid
SUNLinearSolver
modules for this task.
Matrix-based 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.
Matrix-free 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 §2.4.3.8 and
§2.4.4.
If preconditioning is done, user-supplied 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 ARKODE to use for the Newton
systems, after the call to *StepCreate
but before any
calls to ARKodeEvolve()
, the user’s program must create the
appropriate SUNLinearSolver
object and call the function
ARKodeSetLinearSolver()
, as documented below. To create
the SUNLinearSolver
object, the user may call one of the
SUNDIALS-packaged SUNLinSol module constructor routines via a call of
the form
SUNLinearSolver LS = SUNLinSol_*(...);
The current list of SUNDIALS-packaged SUNLinSol modules, and their
constructor routines, may be found in chapter §10.
Alternately, a user-supplied SUNLinearSolver
module may be created
and used. Specific information on how to create such user-provided
modules may be found in §10.1.8.
Once this solver object has been constructed, the user should attach
it to ARKODE via a call to ARKodeSetLinearSolver()
. The
first argument passed to this function is the ARKODE memory pointer
returned by *StepCreate
; the second argument is the
SUNLinearSolver
object created above. The third argument is an
optional SUNMatrix
object to accompany matrix-based
SUNLinearSolver
inputs (for matrix-free linear solvers, the third
argument should be NULL
). A call to this function initializes the
ARKLS linear solver interface, linking it to the ARKODE integrator,
and allows the user to specify additional parameters and routines
pertinent to their choice of linear solver.
-
int ARKodeSetLinearSolver(void *arkode_mem, SUNLinearSolver LS, SUNMatrix J)
This function specifies the
SUNLinearSolver
object that ARKODE should use, as well as a template JacobianSUNMatrix
object (if applicable).- Parameters:
arkode_mem – pointer to the ARKODE memory block.
LS – the
SUNLinearSolver
object to use.J – the template Jacobian
SUNMatrix
object to use (orNULL
if not applicable).
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_MEM_FAIL – there was a memory allocation failure.
ARKLS_ILL_INPUT – ARKLS is incompatible with the provided LS or J input objects, or the current
N_Vector
module.ARK_STEPPER_UNSUPPORTED – linear solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
If LS is a matrix-free linear solver, then the J argument should be
NULL
.If LS is a matrix-based 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 §9 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 in-place, on top of the user-specified 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 ARKODE.
Added in version 6.1.0.
2.4.3.4. Mass matrix solver specification functions
As discussed in §2.2.15.6, if the ODE system involves a non-identity mass matrix \(M\ne I\), then ARKODE must solve linear systems of the form
ARKODE’s ARKLS mass-matrix linear solver interface supports all valid
SUNLinearSolver
modules for this task. For iterative linear
solvers, user-supplied preconditioning can be applied. For the
specification of a preconditioner, see the iterative linear solver
portions of §2.4.3.8 and
§2.4.4. If preconditioning is to be
performed, user-supplied 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 ARKODE to use for mass matrix
systems, after the call to *StepCreate
but before any
calls to ARKodeEvolve()
, the user’s program must create the
appropriate SUNLinearSolver
object and call the function
ARKodeSetMassLinearSolver()
, as documented below. The
first argument passed to this function is the ARKODE memory
pointer returned by *StepCreate
; 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 time-dependent,
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
ARKODE 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 matrix-based, 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 matrix-free, 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 ARKodeSetMassLinearSolver(void *arkode_mem, SUNLinearSolver LS, SUNMatrix M, sunbooleantype time_dep)
This function specifies the
SUNLinearSolver
object that ARKODE should use for mass matrix systems, as well as a templateSUNMatrix
object.- Parameters:
arkode_mem – pointer to the ARKODE 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 time-dependence of the mass matrix.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_MEM_FAIL – there was a memory allocation failure.
ARKLS_ILL_INPUT – ARKLS is incompatible with the provided LS or M input objects, or the current
N_Vector
module.ARK_STEPPER_UNSUPPORTED – non-identity mass matrices are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support non-identity mass matrices.
If LS is a matrix-free linear solver, then the M argument should be
NULL
.If LS is a matrix-based 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 either*StepReInit
orARKodeResize()
are called), with the results reused throughout the entire ARKODE simulation.Unlike the system Jacobian, the system mass matrix is not approximated using finite-differences of any functions provided to ARKODE. Hence, use of the a matrix-based LS requires the user to provide a mass-matrix constructor routine (see
ARKLsMassFn
andARKodeSetMassFn()
).Similarly, the system mass matrix-vector-product is not approximated using finite-differences of any functions provided to ARKODE. Hence, use of a matrix-free LS requires the user to provide a mass-matrix-times-vector product routine (see
ARKLsMassTimesVecFn
andARKodeSetMassTimes()
).Added in version 6.1.0.
2.4.3.5. Nonlinear solver interface functions
When changing the nonlinear solver in ARKODE, after the
call to *StepCreate
but before any calls to
ARKodeEvolve()
, the user’s program must create the
appropriate SUNNonlinearSolver
object and call
ARKodeSetNonlinearSolver()
, as documented below. If any
calls to ARKodeEvolve()
have been made, then ARKODE will
need to be reinitialized by calling *StepReInit
to
ensure that the nonlinear solver is initialized correctly before any
subsequent calls to ARKodeEvolve()
.
The first argument passed to the routine
ARKodeSetNonlinearSolver()
is the ARKODE memory pointer
returned by *StepCreate
; 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 ARKODE integrator.
-
int ARKodeSetNonlinearSolver(void *arkode_mem, SUNNonlinearSolver NLS)
This function specifies the
SUNNonlinearSolver
object that ARKODE should use for implicit stage solves.- Parameters:
arkode_mem – pointer to the ARKODE memory block.
NLS – the
SUNNonlinearSolver
object to use.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_MEM_FAIL – there was a memory allocation failure.
ARK_ILL_INPUT – ARKODE is incompatible with the provided NLS input object.
ARK_STEPPER_UNSUPPORTED – nonlinear solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
ARKODE will use the Newton
SUNNonlinearSolver
module by default; a call to this routine replaces that module with the supplied NLS object.Added in version 6.1.0.
2.4.3.6. Rootfinding initialization function
As described in §2.2.16, while
solving the IVP, ARKODE’s time-stepping modules have the capability to
find the roots of a set of user-defined functions. To activate the
root-finding algorithm, call the following function. This is normally
called only once, prior to the first call to
ARKodeEvolve()
, but if the rootfinding problem is to be
changed during the solution, ARKodeRootInit()
can also be
called prior to a continuation call to ARKodeEvolve()
.
Note
The solution is interpolated to the times at which roots are found.
-
int ARKodeRootInit(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
*StepCreate
, and beforeARKodeEvolve()
.- Parameters:
arkode_mem – pointer to the ARKODE memory block.
nrtfn – number of functions \(g_i\), an integer \(\ge\) 0.
g – name of user-supplied function, of type
ARKRootFn()
, defining the functions \(g_i\) whose roots are sought.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_MEM_FAIL – there was a memory allocation failure.
ARK_ILL_INPUT – nrtfn is greater than zero but g is
NULL
.
Note
To disable the rootfinding feature after it has already been initialized, or to free memory associated with ARKODE’s rootfinding module, call ARKodeRootInit with nrtfn = 0.
Similarly, if a new IVP is to be solved with a call to
*StepReInit
, where the new IVP has no rootfinding problem but the prior one did, then call ARKodeRootInit with nrtfn = 0.Added in version 6.1.0.
2.4.3.7. ARKODE 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 ARKODE 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
ARKodeSetStopTime()
) or has requested rootfinding.
-
int ARKodeEvolve(void *arkode_mem, sunrealtype tout, N_Vector yout, sunrealtype *tret, int itask)
Integrates the ODE over an interval in \(t\).
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
tout – the next time at which a computed solution is desired.
yout – the computed solution vector.
tret – the time corresponding to yout (output).
itask –
a flag indicating the job of the solver for the next user step.
The ARK_NORMAL option causes the solver to take internal steps until it has just overtaken a user-specified output time, tout, in the direction of integration, i.e. \(t_{n-1} <\) tout \(\le t_{n}\) for forward integration, or \(t_{n} \le\) tout \(< t_{n-1}\) for backward integration. If interpolation is enabled (on by default), it will then compute an approximation to the solution \(y(tout)\) by interpolation (as described in §2.2.2). Otherwise, the solution at the time reached by the solver is returned, \(y(tret)\).
The ARK_ONE_STEP option tells the solver to only take a single internal step, \(y_{n-1} \to y_{n}\), and return the solution at that point, \(y_{n}\), in the vector yout.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_ROOT_RETURN –
ARKodeEvolve()
succeeded, and found one or more roots. If the number of root functions, nrtfn, is greater than 1, callARKodeGetRootInfo()
to see which \(g_i\) were found to have a root at (*tret).ARK_TSTOP_RETURN –
ARKodeEvolve()
succeeded and returned at tstop.ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_NO_MALLOC –
arkode_mem
was not allocated.ARK_ILL_INPUT –
one of the inputs to
ARKodeEvolve()
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 time-stepping.
The linear solver initialization function (called by the user after calling
*StepCreate
) failed to set the linear solver-specific lsolve field inarkode_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 – the solver took mxstep internal steps but could not reach tout. The default value for mxstep is MXSTEP_DEFAULT = 500.
ARK_TOO_MUCH_ACC – the solver could not satisfy the accuracy demanded by the user for some internal step.
ARK_ERR_FAILURE – error test failures occurred either too many times (ark_maxnef) during one internal time step or occurred with \(|h| = h_{min}\).
ARK_CONV_FAILURE – either convergence test failures occurred too many times (ark_maxncf) during one internal time step or occurred with \(|h| = h_{min}\).
ARK_LINIT_FAIL – the linear solver’s initialization function failed.
ARK_LSETUP_FAIL – the linear solver’s setup routine failed in an unrecoverable manner.
ARK_LSOLVE_FAIL – the linear solver’s solve routine failed in an unrecoverable manner.
ARK_MASSINIT_FAIL – the mass matrix solver’s initialization function failed.
ARK_MASSSETUP_FAIL – the mass matrix solver’s setup routine failed.
ARK_MASSSOLVE_FAIL – the mass matrix solver’s solve routine failed.
ARK_VECTOROP_ERR – a vector operation error occurred.
ARK_DOMEIG_FAIL – the dominant eigenvalue function failed. It is either not provided or returns an illegal value.
ARK_MAX_STAGE_LIMIT_FAIL – stepper failed to achieve stable results. Either reduce the step size or increase the stage_max_limit
Note
The input vector yout can use the same memory as the vector y0 of initial conditions that was passed to
*StepCreate
.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
ARKodeEvolve()
failures.Since interpolation may reduce the accuracy in the reported solution, if full method accuracy is desired the user should issue a call to
ARKodeSetStopTime()
before the call toARKodeEvolve()
to specify a fixed stop time to end the time step and return to the user. Upon return fromARKodeEvolve()
, a copy of the internal solution \(y_{n}\) will be returned in the vector yout. Once the integrator returns at a tstop time, any future testing for tstop is disabled (and can be re-enabled only though a new call toARKodeSetStopTime()
).On any error return in which one or more internal steps were taken by
ARKodeEvolve()
, 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.Added in version 6.1.0.
2.4.3.8. Optional input functions
There are numerous optional input parameters that control the behavior of ARKODE, 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 ARKODE 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 ARKODE options (Optional inputs for ARKODE),
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 ARKODE, relying on the default set of solver parameters, the reader can skip to section on user-supplied functions, §2.4.4.
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 ARKodeSet***
function can generally be made
from the user’s calling program at any time after creation of the ARKODE
solver via *StepCreate
, and, the function exited successfully, takes effect immediately.
ARKodeSet***
functions that cannot be called at any time note
this in the “notes” section of the function documentation.
2.4.3.8.1. Optional inputs for ARKODE
Optional input |
Function name |
Default |
---|---|---|
Return ARKODE parameters to their defaults |
internal |
|
Set integrator method order |
4 |
|
Set dense output interpolation type (SPRKStep) |
|
|
Set dense output interpolation type (others) |
|
|
Set dense output polynomial degree |
5 |
|
Disable time step adaptivity (fixed-step mode) |
disabled |
|
Set forward or backward integration direction |
0.0 |
|
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}\) |
undefined |
|
Interpolate at \(t_{stop}\) |
|
|
Disable the stop time |
N/A |
|
Supply a pointer for user data |
|
|
Maximum no. of ARKODE error test failures |
7 |
|
Set inequality constraints on solution |
|
|
Set max number of constraint failures |
10 |
-
int ARKodeSetDefaults(void *arkode_mem)
Resets all optional input parameters to ARKODE’s original default values.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
Note
Does not change the user_data pointer or any parameters within the specified time-stepping module.
Also leaves alone any data structures or options related to root-finding (those can be reset using
ARKodeRootInit()
).Added in version 6.1.0.
-
int ARKodeSetOrder(void *arkode_mem, int ord)
Specifies the order of accuracy for the IVP integration method.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
ord – requested order of accuracy.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
ARK_STEPPER_UNSUPPORTED – this option is not supported by the time-stepping module.
Note
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 \(2 \le\) ord \(\le 5\). Any illegal input will result in the default value of 4.
Since ord affects the memory requirements for the internal ARKODE memory block, it cannot be changed after the first call to
ARKodeEvolve()
, unless*StepReInit
is called.Added in version 6.1.0.
-
int ARKodeSetInterpolantType(void *arkode_mem, int itype)
Specifies the interpolation type used for dense output (interpolation of solution output values) and implicit method predictors. By default, Hermite interpolation is used except with SPRK methods where Lagrange interpolation is the default.
This routine must be called after the calling a stepper constructor. After the first call to
ARKodeEvolve()
the interpolation type may not be changed without first calling a stepperReInit
function.The Hermite interpolation module (
ARK_INTERP_HERMITE
) is described in §2.2.2.1, and the Lagrange interpolation module (ARK_INTERP_LAGRANGE
) is described in §2.2.2.2.ARK_INTERP_NONE
will disable interpolation.When interpolation is disabled, using rootfinding is not supported, implicit methods must use the trivial predictor (the default option), and interpolation at stop times cannot be used (interpolating at stop times is disabled by default). With interpolation disabled, calling
ARKodeEvolve()
inARK_NORMAL
mode will return at or past the requested output time (setting a stop time may still be used to halt the integrator at a specific time).Disabling interpolation will reduce the memory footprint of an integrator by two or more state vectors (depending on the interpolant type and degree) which can be beneficial when interpolation is not needed e.g., when integrating to a final time without output in between or using a solver from ARKODE as a fast time scale integrator with MRI methods.
This routine frees any previously-allocated interpolation module, and re-creates one according to the specified argument.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
itype – requested interpolant type:
ARK_INTERP_HERMITE
,ARK_INTERP_LAGRANGE
, orARK_INTERP_NONE
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_MEM_FAIL – the interpolation module could not be allocated.
ARK_ILL_INPUT – the itype argument is not recognized or the interpolation module has already been initialized.
Changed in version 6.1.0: This function replaces stepper specific versions in ARKStep, ERKStep, MRIStep, and SPRKStep.
Added the
ARK_INTERP_NONE
option to disable interpolation.Values set by a previous call to
ARKStepSetInterpolantDegree()
are no longer nullified by a call toARKStepSetInterpolantType()
.
-
int ARKodeSetInterpolantDegree(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).
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
degree – requested polynomial degree.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
or the interpolation module areNULL
.ARK_INTERP_FAIL – this was called after
ARKodeEvolve()
.ARK_ILL_INPUT – an argument had an illegal value or the interpolation module has already been initialized.
Note
Allowed values are between 0 and 5.
This routine should be called before
ARKodeEvolve()
. After the first call toARKodeEvolve()
the interpolation degree may not be changed without first calling*StepReInit
.If a user calls both this routine and
ARKodeSetInterpolantType()
, thenARKodeSetInterpolantType()
must be called first.Since the accuracy of any polynomial interpolant is limited by the accuracy of the time-step solutions on which it is based, the actual polynomial degree that is used by ARKODE will be the minimum of \(q-1\) and the input degree, for \(q > 1\) where \(q\) is the order of accuracy for the time integration method.
When \(q=1\), a linear interpolant is the default to ensure values obtained by the integrator are returned at the ends of the time interval.
Added in version 6.1.0.
-
int ARKodeSetFixedStep(void *arkode_mem, sunrealtype hfixed)
Disables time step adaptivity within ARKODE, and specifies the fixed time step size to use for the following internal step(s).
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
hfixed – value of the fixed step size to use.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
Note
Pass 0.0 to return ARKODE to the default (adaptive-step) mode – this is only allowed when using a time-stepping module that supports temporal adaptivity.
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 code-to-code verification testing purposes.
When using
ARKodeSetFixedStep()
, any values provided to the functionsARKodeSetInitStep()
,ARKodeSetMaxErrTestFails()
,ARKodeSetCFLFraction()
,ARKodeSetErrorBias()
,ARKodeSetFixedStepBounds()
,ARKodeSetMaxCFailGrowth()
,ARKodeSetMaxEFailGrowth()
,ARKodeSetMaxFirstGrowth()
,ARKodeSetMaxGrowth()
,ARKodeSetMinReduction()
,ARKodeSetSafetyFactor()
,ARKodeSetSmallNumEFails()
,ARKodeSetStabilityFn()
, andARKodeSetAdaptController()
will be ignored, since temporal adaptivity is disabled.If both
ARKodeSetFixedStep()
andARKodeSetStopTime()
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 toARKodeSetFixedStep()
must be made prior to callingARKodeEvolve()
to resume integration.It is not recommended that
ARKodeSetFixedStep()
be used in concert withARKodeSetMaxStep()
orARKodeSetMinStep()
, 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.Added in version 6.1.0.
-
int ARKodeSetStepDirection(void *arkode_mem, sunrealtype stepdir)
Specifies the direction of integration (forward or backward).
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
stepdir – value whose sign determines the direction. A positive value selects forward integration, a negative value selects backward integration, and zero leaves the current direction unchanged.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
Note
The step direction can only be set after a call to either
*Create
,*StepReInit
, orARKodeReset()
but before a call toARKodeEvolve()
.When the direction changes for an adaptive method, the adaptivity controller and next step size are reset. A new initial step size will be estimated at the next call to
ARKodeEvolve()
or can be specified withARKodeSetInitStep()
.Added in version 6.2.0.
-
int ARKodeSetInitStep(void *arkode_mem, sunrealtype hin)
Specifies the initial time step size ARKODE should use after initialization, re-initialization, or resetting.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
hin – value of the initial step to be attempted \((\ne 0)\).
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
Note
Pass 0.0 to use the default value – this is only allowed when using a time-stepping module that supports temporal adaptivity.
By default, ARKODE 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.
Added in version 6.1.0.
-
int ARKodeSetMaxHnilWarns(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 ARKODE will instead return with an error.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
mxhnil – maximum allowed number of warning messages \((>0)\).
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
ARK_STEPPER_UNSUPPORTED – adaptive step sizes are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support temporal adaptivity.
The default value is 10; set mxhnil to zero to specify this default.
A negative value indicates that no warning messages should be issued.
Added in version 6.1.0.
-
int ARKodeSetMaxNumSteps(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 ARKODE will return with an error.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
mxsteps – maximum allowed number of internal steps.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
Note
Passing mxsteps = 0 results in ARKODE using the default value (500).
Passing mxsteps < 0 disables the test (not recommended).
Added in version 6.1.0.
-
int ARKodeSetMaxStep(void *arkode_mem, sunrealtype hmax)
Specifies the upper bound on the magnitude of the time step size.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
hmax – maximum absolute value of the time step size \((\ge 0)\).
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
ARK_STEPPER_UNSUPPORTED – adaptive step sizes are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support temporal adaptivity.
Pass hmax \(\le 0.0\) to set the default value of \(\infty\).
Added in version 6.1.0.
-
int ARKodeSetMinStep(void *arkode_mem, sunrealtype hmin)
Specifies the lower bound on the magnitude of the time step size.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
hmin – minimum absolute value of the time step size \((\ge 0)\).
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
ARK_STEPPER_UNSUPPORTED – adaptive step sizes are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support temporal adaptivity.
Pass hmin \(\le 0.0\) to set the default value of 0.
Added in version 6.1.0.
-
int ARKodeSetStopTime(void *arkode_mem, sunrealtype tstop)
Specifies the value of the independent variable \(t\) past which the solution is not to proceed.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
tstop – stopping time for the integrator.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
Note
The default is that no stop time is imposed.
Once the integrator returns at a stop time, any future testing for
tstop
is disabled (and can be re-enabled only though a new call toARKodeSetStopTime()
).A stop time not reached before a call to
*StepReInit
orARKodeReset()
will remain active but can be disabled by callingARKodeClearStopTime()
.Added in version 6.1.0.
-
int ARKodeSetInterpolateStopTime(void *arkode_mem, sunbooleantype interp)
Specifies that the output solution should be interpolated when the current \(t\) equals the specified
tstop
(instead of merely copying the internal solution \(y_n\)).- Parameters:
arkode_mem – pointer to the ARKODE memory block.
interp – flag indicating to use interpolation (1) or copy (0).
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.
Added in version 6.1.0.
-
int ARKodeClearStopTime(void *arkode_mem)
Disables the stop time set with
ARKodeSetStopTime()
.- Parameters:
arkode_mem – pointer to the ARKODE memory block.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.
Note
The stop time can be re-enabled though a new call to
ARKodeSetStopTime()
.Added in version 6.1.0.
-
int ARKodeSetUserData(void *arkode_mem, void *user_data)
Specifies the user data block user_data and attaches it to the main ARKODE memory block.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
user_data – pointer to the user data.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
Note
If specified, the pointer to user_data is passed to all user-supplied 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
ARKodeSetLinearSolver()
and/orARKodeSetMassLinearSolver()
.Added in version 6.1.0.
-
int ARKodeSetMaxErrTestFails(void *arkode_mem, int maxnef)
Specifies the maximum number of error test failures permitted in attempting one step, before returning with an error.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
maxnef – maximum allowed number of error test failures \((>0)\).
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
ARK_STEPPER_UNSUPPORTED – adaptive step sizes are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support temporal adaptivity.
The default value is 7; set maxnef \(\le 0\) to specify this default.
Added in version 6.1.0.
-
int ARKodeSetConstraints(void *arkode_mem, N_Vector constraints)
Specifies a vector defining inequality constraints for each component of the solution vector \(y\).
- Parameters:
arkode_mem – pointer to the ARKODE 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 values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – the constraints vector contains illegal values.
ARK_STEPPER_UNSUPPORTED – adaptive step sizes are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support temporal adaptivity.
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
ARKodeResize()
inequality constraint checking will be disabled and a call toARKodeSetConstraints()
is required to re-enable constraint checking.Since constraint-handling 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
ARKodeSetConstraints()
andARKodeSetFixedStep()
are incompatible, and should not be used simultaneously.Added in version 6.1.0.
-
int ARKodeSetMaxNumConstrFails(void *arkode_mem, int maxfails)
Specifies the maximum number of constraint failures in a step before ARKODE will return with an error.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
maxfails – maximum allowed number of constrain failures.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_STEPPER_UNSUPPORTED – adaptive step sizes are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support temporal adaptivity.
Passing maxfails <= 0 results in ARKODE using the default value (10).
Added in version 6.1.0.
2.4.3.8.2. 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 §2.2.11.
Optional input |
Function name |
Default |
---|---|---|
Provide a |
PID |
|
Adjust the method order used in the controller |
-1 |
|
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 |
2 |
|
Explicit stability function |
none |
|
Set accumulated error estimation type |
none |
|
Reset accumulated error |
-
int ARKodeSetAdaptController(void *arkode_mem, SUNAdaptController C)
Sets a user-supplied time-step controller object.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
C – user-supplied time adaptivity controller.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_MEM_FAIL – C was
NULL
and the PID controller could not be allocated.ARK_STEPPER_UNSUPPORTED – adaptive step sizes are not supported by the current time-stepping module.
Note
If C is
NULL
then the PID controller will be created (see §12.2).This is only compatible with time-stepping modules that support temporal adaptivity.
Not all time-stepping modules are compatible with all types of
SUNAdaptController
objects. While all steppers that support temporal adaptivity support controllers withSUNAdaptController_Type
typeSUN_ADAPTCONTROLLER_H
, only MRIStep supports inputs with typeSUN_ADAPTCONTROLLER_MRI_H_TOL
.Added in version 6.1.0.
-
int ARKodeSetAdaptivityAdjustment(void *arkode_mem, int adjust)
Called by a user to adjust the method order supplied to the temporal adaptivity controller. For example, if the user expects order reduction due to problem stiffness, they may request that the controller assume a reduced order of accuracy for the method by specifying a value \(adjust < 0\).
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
adjust – adjustment factor (default is -1).
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
ARK_STEPPER_UNSUPPORTED – adaptive step sizes are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support temporal adaptivity.
This should be called prior to calling
ARKodeEvolve()
, and can only be reset following a call to*StepReInit
.Added in version 6.1.0.
-
int ARKodeSetCFLFraction(void *arkode_mem, sunrealtype cfl_frac)
Specifies the fraction of the estimated explicitly stable step to use.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
cfl_frac – maximum allowed fraction of explicitly stable step (default is 0.5).
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
ARK_STEPPER_UNSUPPORTED – adaptive step sizes are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support temporal adaptivity.
Any non-positive parameter will imply a reset to the default value.
Added in version 6.1.0.
-
int ARKodeSetErrorBias(void *arkode_mem, sunrealtype bias)
Specifies the bias to be applied to the error estimates within accuracy-based adaptivity strategies.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
bias – bias applied to error in accuracy-based time step estimation (default is 1.5).
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
ARK_STEPPER_UNSUPPORTED – adaptive step sizes are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support temporal adaptivity.
Any value below 1.0 will imply a reset to the default value.
If both this and one of the stepper
SetAdaptivityMethod
functions orARKodeSetAdaptController()
will be called, then this routine must be called second.Added in version 6.1.0.
-
int ARKodeSetFixedStepBounds(void *arkode_mem, sunrealtype lb, sunrealtype ub)
Specifies the step growth interval in which the step size will remain unchanged.
- Parameters:
arkode_mem – pointer to the ARKODE 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 values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
ARK_STEPPER_UNSUPPORTED – adaptive step sizes are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support temporal adaptivity.
Any interval not containing 1.0 will imply a reset to the default values.
Added in version 6.1.0.
-
int ARKodeSetMaxCFailGrowth(void *arkode_mem, sunrealtype etacf)
Specifies the maximum step size growth factor upon an algebraic solver convergence failure on a stage solve within a step, \(\eta_{cf}\) from §2.2.15.3.1.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
etacf – time step reduction factor on a nonlinear solver convergence failure (default is 0.25).
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
ARK_STEPPER_UNSUPPORTED – adaptive step sizes are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support temporal adaptivity.
Any value outside the interval \((0,1]\) will imply a reset to the default value.
Added in version 6.1.0.
-
int ARKodeSetMaxEFailGrowth(void *arkode_mem, sunrealtype etamxf)
Specifies the maximum step size growth factor upon multiple successive accuracy-based error failures in the solver.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
etamxf – time step reduction factor on multiple error fails (default is 0.3).
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
ARK_STEPPER_UNSUPPORTED – adaptive step sizes are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support temporal adaptivity.
Any value outside the interval \((0,1]\) will imply a reset to the default value.
Added in version 6.1.0.
-
int ARKodeSetMaxFirstGrowth(void *arkode_mem, sunrealtype etamx1)
Specifies the maximum allowed growth factor in step size following the very first integration step.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
etamx1 – maximum allowed growth factor after the first time step (default is 10000.0).
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
ARK_STEPPER_UNSUPPORTED – adaptive step sizes are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support temporal adaptivity.
Any value \(\le 1.0\) will imply a reset to the default value.
Added in version 6.1.0.
-
int ARKodeSetMaxGrowth(void *arkode_mem, sunrealtype mx_growth)
Specifies the maximum allowed growth factor in step size between consecutive steps in the integration process.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
mx_growth – maximum allowed growth factor between consecutive time steps (default is 20.0).
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
ARK_STEPPER_UNSUPPORTED – adaptive step sizes are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support temporal adaptivity.
Any value \(\le 1.0\) will imply a reset to the default value.
Added in version 6.1.0.
-
int ARKodeSetMinReduction(void *arkode_mem, sunrealtype eta_min)
Specifies the minimum allowed reduction factor in step size between step attempts, resulting from a temporal error failure in the integration process.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
eta_min – minimum allowed reduction factor in time step after an error test failure (default is 0.1).
- Return values:
ARK_STEPPER_UNSUPPORTED – adaptive step sizes are not supported by the current time-stepping module.
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
Note
This is only compatible with time-stepping modules that support temporal adaptivity.
Any value outside the interval \((0,1)\) will imply a reset to the default value.
Added in version 6.1.0.
-
int ARKodeSetSafetyFactor(void *arkode_mem, sunrealtype safety)
Specifies the safety factor to be applied to the accuracy-based estimated step.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
safety – safety factor applied to accuracy-based time step (default is 0.96).
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
ARK_STEPPER_UNSUPPORTED – adaptive step sizes are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support temporal adaptivity.
Any value \(\le 0\) will imply a reset to the default value.
Added in version 6.1.0.
-
int ARKodeSetSmallNumEFails(void *arkode_mem, int small_nef)
Specifies the threshold for “multiple” successive error failures before the etamxf parameter from
ARKodeSetMaxEFailGrowth()
is applied.- Parameters:
arkode_mem – pointer to the ARKODE memory block.
small_nef – bound to determine ‘multiple’ for etamxf (default is 2).
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
ARK_STEPPER_UNSUPPORTED – adaptive step sizes are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support temporal adaptivity.
Any value \(\le 0\) will imply a reset to the default value.
Added in version 6.1.0.
-
int ARKodeSetStabilityFn(void *arkode_mem, ARKExpStabFn EStab, void *estab_data)
Sets the problem-dependent function to estimate a stable time step size for the explicit portion of the ODE system.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
EStab – name of user-supplied stability function.
estab_data – pointer to user data passed to EStab every time it is called.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
ARK_STEPPER_UNSUPPORTED – adaptive step sizes are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support temporal adaptivity.
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 accuracy-based adaptivity may be sufficient for retaining stability, but this can be quite useful for problems where the explicit right-hand side function \(f^E(t,y)\) contains stiff terms.
Added in version 6.1.0.
The following routines are used to control algorithms that ARKODE can use to estimate
the accumulated temporal error over multiple time steps. While these may be informational
for users on their applications, this functionality is required when using multirate
temporal adaptivity in MRIStep via the SUNAdaptController_MRIHTol
module. For time-stepping modules that compute both a solution and embedding, \(y_n\)
and \(\tilde{y}_n\), these may be combined to create a vector-valued local temporal error
estimate for the current internal step, \(y_n - \tilde{y}_n\). These local errors may be
accumulated by ARKODE in a variety of ways, as determined by the enumerated type
ARKAccumError
. In each of the cases below, the accumulation is taken over all steps
since the most recent call to either ARKodeSetAccumulatedErrorType()
or
ARKodeResetAccumulatedError()
. Below the set \(\mathcal{S}\) contains
the indices of the steps since the last call to either of the aforementioned functions.
The norm is taken using the tolerance-informed error-weight vector (see
ARKodeGetErrWeights()
), and reltol
is the user-specified relative solution
tolerance.
-
enum ARKAccumError
The type of error accumulation that ARKODE should use.
Added in version 6.2.0.
-
enumerator ARK_ACCUMERROR_NONE
No accumulation should be performed
-
enumerator ARK_ACCUMERROR_MAX
Computes \(\text{reltol} \max\limits_{i \in \mathcal{S}} \|y_i - \tilde{y}_i\|_{WRMS}\)
-
enumerator ARK_ACCUMERROR_SUM
Computes \(\text{reltol} \sum\limits_{i \in \mathcal{S}} \|y_i - \tilde{y}_i\|_{WRMS}\)
-
enumerator ARK_ACCUMERROR_AVG
Computes \(\frac{\text{reltol}}{\Delta t_{\mathcal{S}}} \sum\limits_{i \in \mathcal{S}} h_i \|y_i - \tilde{y}_i\|_{WRMS}\), where \(h_i\) is the step size used when computing \(y_i\), and \(\Delta t_{\mathcal{S}}\) denotes the elapsed time over which \(\mathcal{S}\) is taken.
-
enumerator ARK_ACCUMERROR_NONE
-
int ARKodeSetAccumulatedErrorType(void *arkode_mem, ARKAccumError accum_type)
Sets the strategy to use for accumulating a temporal error estimate over multiple time steps. By default, ARKODE will not accumulate any local error estimates (i.e., the default accum_type is
ARK_ACCUMERROR_NONE
).A non-default error accumulation strategy can be disabled by calling
ARKodeSetAccumulatedErrorType()
with the argumentARK_ACCUMERROR_NONE
.- Parameters:
arkode_mem – pointer to the ARKODE memory block.
accum_type – accumulation strategy.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
ARK_STEPPER_UNSUPPORTED – temporal error estimation is not supported by the current time-stepping module.
Added in version 6.2.0.
-
int ARKodeResetAccumulatedError(void *arkode_mem)
Resets the accumulated temporal error estimate, that was triggered by a previous call to
ARKodeSetAccumulatedErrorType()
.- Parameters:
arkode_mem – pointer to the ARKODE memory block.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
ARK_STEPPER_UNSUPPORTED – temporal error estimation is not supported by the current time-stepping module.
Added in version 6.2.0.
2.4.3.8.3. Optional inputs for implicit stage solves
The mathematical explanation for the nonlinear solver strategies used by ARKODE, including how each of the parameters below is used within the code, is provided in §2.2.15.1.
Optional input |
Function name |
Default |
---|---|---|
Specify that the implicit RHS is linear |
|
|
Specify that the implicit RHS nonlinear |
|
|
Specify that the implicit RHS is autonomous |
|
|
Implicit predictor method |
0 |
|
User-provided 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 the implicit RHS is deduced after a nonlinear solve |
|
-
int ARKodeSetLinear(void *arkode_mem, int timedepend)
Specifies that the implicit portion of the problem is linear.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
timedepend – flag denoting whether the Jacobian of \(f^I(t,y)\) is time-dependent (1) or not (0).
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
ARK_STEPPER_UNSUPPORTED – implicit solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
Tightens the linear solver tolerances and takes only a single Newton iteration. Calls
ARKodeSetDeltaGammaMax()
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 fixed-point solver).When \(f^I(t,y)\) is time-dependent, 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.
Added in version 6.1.0.
-
int ARKodeSetNonlinear(void *arkode_mem)
Specifies that the implicit portion of the problem is nonlinear.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
ARK_STEPPER_UNSUPPORTED – implicit solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
This is the default behavior of ARKODE, so the function is primarily useful to undo a previous call to
ARKodeSetLinear()
. CallsARKodeSetDeltaGammaMax()
to reset the step size ratio threshold to the default value.Added in version 6.1.0.
-
int ARKodeSetAutonomous(void *arkode_mem, sunbooleantype autonomous)
Specifies that the implicit portion of the problem is autonomous i.e., does not explicitly depend on time.
When using an implicit or ImEx method with the trivial predictor, this option enables reusing the implicit right-hand side evaluation at the predicted state across stage solves within a step. This reuse reduces the total number of implicit RHS function evaluations.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
autonomous – flag denoting if the implicit RHS function, \(f^I(t,y)\), is autonomous (
SUNTRUE
) or non-autonomous (SUNFALSE
).
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
ARK_STEPPER_UNSUPPORTED – implicit solvers are not supported by the current time-stepping module.
Warning
Results may differ when enabling both
ARKodeSetAutonomous()
andARKodeSetDeduceImplicitRhs()
with a stiffly accurate implicit method and using the trivial predictor. The differences are due to reusing the deduced implicit right-hand side (RHS) value in the initial nonlinear residual computation rather than evaluating the implicit RHS function. The significance of the difference will depend on how well the deduced RHS approximates the RHS evaluated at the trivial predictor. This behavior can be observed inexamples/arkode/C_serial/ark_brusselator.c
by comparing the outputs withARKodeSetAutonomous()
enabled/disabled.Similarly programs that assume the nonlinear residual will always call the implicit RHS function will need to be updated to account for the RHS value reuse when using
ARKodeSetAutonomous()
. For example,examples/arkode/C_serial/ark_KrylovDemo_prec.c
assumes that the nonlinear residual will be called and will evaluate the implicit RHS function before calling the preconditioner setup function. Based on this assumption, this example code saves some computations in the RHS evaluation for reuse in the preconditioner setup. However, whenARKodeSetAutonomous()
is enabled, the call to the nonlinear residual before the preconditioner setup reuses a saved RHS evaluation and the saved data is actually from an earlier RHS evaluation that is not consistent with the state and RHS values passed to the preconditioner setup function. For this example, the code should not save data in the RHS evaluation but instead evaluate the necessary quantities within the preconditioner setup function using the input values.Added in version 6.1.0.
-
int ARKodeSetPredictorMethod(void *arkode_mem, int method)
Specifies the method from §2.2.15.5 to use for predicting implicit solutions.
- Parameters:
arkode_mem – pointer to the ARKODE 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 first-order predictor for distant RK stages,
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
ARK_STEPPER_UNSUPPORTED – implicit solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
The default value is 0. If method is set to an undefined value, this default predictor will be used.
Added in version 6.1.0.
-
int ARKodeSetStagePredictFn(void *arkode_mem, ARKStagePredictFn PredictStage)
Sets the user-supplied function to update the implicit stage predictor prior to execution of the nonlinear or linear solver algorithms that compute the implicit stage solution.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
PredictStage – name of user-supplied predictor function. If
NULL
, then any previously-provided stage prediction function will be disabled.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_STEPPER_UNSUPPORTED – implicit solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
See §2.4.4.6 for more information on this user-supplied routine.
Added in version 6.1.0.
-
int ARKodeSetNlsRhsFn(void *arkode_mem, ARKRhsFn nls_fi)
Specifies an alternative implicit right-hand side function for evaluating \(f^I(t,y)\) within nonlinear system function evaluations (2.43) - (2.45).
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
nls_fi – the alternative C function for computing the right-hand side function \(f^I(t,y)\) in the ODE.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_STEPPER_UNSUPPORTED – implicit solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
The default is to use the implicit right-hand side function provided to the stepper constructor in nonlinear system functions. If the input implicit right-hand side function is
NULL
, the default is used.When using a non-default nonlinear solver, this function must be called after
ARKodeSetNonlinearSolver()
.Added in version 6.1.0.
-
int ARKodeSetMaxNonlinIters(void *arkode_mem, int maxcor)
Specifies the maximum number of nonlinear solver iterations permitted per implicit stage solve within each time step.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
maxcor – maximum allowed solver iterations per stage \((>0)\).
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value or if the SUNNONLINSOL module is
NULL
.ARK_NLS_OP_ERR – the SUNNONLINSOL object returned a failure flag.
ARK_STEPPER_UNSUPPORTED – implicit solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
The default value is 3; set maxcor \(\le 0\) to specify this default.
Added in version 6.1.0.
-
int ARKodeSetNonlinConvCoef(void *arkode_mem, sunrealtype nlscoef)
Specifies the safety factor \(\epsilon\) used within the nonlinear solver convergence test (2.58).
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
nlscoef – coefficient in nonlinear solver convergence test \((>0.0)\).
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
ARK_STEPPER_UNSUPPORTED – implicit solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
The default value is 0.1; set nlscoef \(\le 0\) to specify this default.
Added in version 6.1.0.
-
int ARKodeSetNonlinCRDown(void *arkode_mem, sunrealtype crdown)
Specifies the constant \(c_r\) used in estimating the nonlinear solver convergence rate (2.57).
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
crdown – nonlinear convergence rate estimation constant (default is 0.3).
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
ARK_STEPPER_UNSUPPORTED – implicit solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
Any non-positive parameter will imply a reset to the default value.
Added in version 6.1.0.
-
int ARKodeSetNonlinRDiv(void *arkode_mem, sunrealtype rdiv)
Specifies the nonlinear correction threshold \(r_{div}\) from (2.59), beyond which the iteration will be declared divergent.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
rdiv – tolerance on nonlinear correction size ratio to declare divergence (default is 2.3).
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
ARK_STEPPER_UNSUPPORTED – implicit solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
Any non-positive parameter will imply a reset to the default value.
Added in version 6.1.0.
-
int ARKodeSetMaxConvFails(void *arkode_mem, int maxncf)
Specifies the maximum number of nonlinear solver convergence failures permitted during one step, \(max_{ncf}\) from §2.2.15.3.1, before ARKODE will return with an error.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
maxncf – maximum allowed nonlinear solver convergence failures per step \((>0)\).
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
ARK_STEPPER_UNSUPPORTED – implicit solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
The default value is 10; set maxncf \(\le 0\) to specify this default.
Upon each convergence failure, ARKODE 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
ARKodeSetMaxCFailGrowth()
).Added in version 6.1.0.
-
int ARKodeSetDeduceImplicitRhs(void *arkode_mem, sunbooleantype deduce)
Specifies if implicit stage derivatives are deduced without evaluating \(f^I\). See §2.2.15.1 for more details.
- Parameters:
arkode_mem – pointer to the ARKODE 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 values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_STEPPER_UNSUPPORTED – implicit solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
Added in version 6.1.0.
2.4.3.8.4. Linear solver interface optional input functions
The mathematical explanation of the linear solver methods available to ARKODE is provided in §2.2.15.2. We group the user-callable routines into four categories: general routines concerning the update frequency for matrices and/or preconditioners, optional inputs for matrix-based linear solvers, optional inputs for matrix-free linear solvers, and optional inputs for iterative linear solvers. We note that the matrix-based and matrix-free groups are mutually exclusive, whereas the “iterative” tag can apply to either case.
2.4.3.8.4.1. Optional inputs for the ARKLS linear solver interface
As discussed in §2.2.15.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, ARKODE provides user-callable 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 right-hand 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
ARKodeSetLSetupFrequency()
. 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.
Jacobian information is considered out-of-date when \(msbj\) or more steps
have been completed since the last update, in which case it will be recomputed during the next
linear solver setup call. The value of \(msbj\) is controlled with the
msbj
argument to ARKodeSetJacEvalFrequency()
.
For linear-solvers with user-supplied 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
user-supplied ARKLsPrecSetupFn
). For matrix-based 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 user-supplied 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 ARKodeSetDeltaGammaMax(void *arkode_mem, sunrealtype dgmax)
Specifies a scaled step size ratio tolerance, \(\Delta\gamma_{max}\) from §2.2.15.2.3, beyond which the linear solver setup routine will be signaled.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
dgmax – tolerance on step size ratio change before calling linear solver setup routine (default is 0.2).
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
ARK_STEPPER_UNSUPPORTED – implicit solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
Any non-positive parameter will imply a reset to the default value.
Added in version 6.1.0.
-
int ARKodeSetLSetupFrequency(void *arkode_mem, int msbp)
Specifies the frequency of calls to the linear solver setup routine, \(msbp\) from §2.2.15.2.3.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
msbp – the linear solver setup frequency.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_STEPPER_UNSUPPORTED – implicit solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
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.
Added in version 6.1.0.
-
int ARKodeSetJacEvalFrequency(void *arkode_mem, long int msbj)
Specifies the number of steps after which the Jacobian information is considered out-of-date, \(msbj\) from §2.2.15.2.3.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
msbj – the Jacobian re-computation or preconditioner update frequency.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_LMEM_NULL – the linear solver memory was
NULL
.ARK_STEPPER_UNSUPPORTED – implicit solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
If
nstlj
is the step number at which the Jacobian information was lasted updated andnst
is the current step number,nst - nstlj >= msbj
indicates that the Jacobian information will be updated during the next linear solver setup call.As the Jacobian update frequency is only checked within calls to the linear solver setup routine, Jacobian information may be more than
msbj
steps old when updated depending on when a linear solver setup call occurs. See §2.2.15.2.3 for more information on when linear solver setups are performed.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
ARKodeSetLinearSolver()
.Added in version 6.1.0.
2.4.3.8.4.2. Optional inputs for matrix-based 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 matrix-based 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 user-supplied
Jacobian function, ARKODE provides the function ARKodeSetJacFn()
.
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 user-supplied linear system function instead, ARKODE provides the function
ARKodeSetLinSysFn()
.
If the ODE system involves a non-identity mass matrix, \(M\ne I\), matrix-based 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
ARKodeSetMassFn()
.
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 §10.2.1 for more details.
The function ARKodeSetLinearSolutionScaling()
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
user-supplied Jacobian, linear system or mass matrix functions, without using global
data in the program. The user data pointer may be specified through
ARKodeSetUserData()
.
-
int ARKodeSetJacFn(void *arkode_mem, ARKLsJacFn jac)
Specifies the Jacobian approximation routine to be used for the matrix-based solver with the ARKLS interface.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
jac – name of user-supplied Jacobian approximation function.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_LMEM_NULL – the linear solver memory was
NULL
.ARK_STEPPER_UNSUPPORTED – implicit solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
This routine must be called after the ARKLS linear solver interface has been initialized through a call to
ARKodeSetLinearSolver()
.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 §2.4.4.Added in version 6.1.0.
-
int ARKodeSetLinSysFn(void *arkode_mem, ARKLsLinSysFn linsys)
Specifies the linear system approximation routine to be used for the matrix-based solver with the ARKLS interface.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
linsys – name of user-supplied linear system approximation function.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_LMEM_NULL – the linear solver memory was
NULL
.ARK_STEPPER_UNSUPPORTED – implicit solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
This routine must be called after the ARKLS linear solver interface has been initialized through a call to
ARKodeSetLinearSolver()
.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 §2.4.4.Added in version 6.1.0.
-
int ARKodeSetMassFn(void *arkode_mem, ARKLsMassFn mass)
Specifies the mass matrix approximation routine to be used for the matrix-based solver with the ARKLS interface.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
mass – name of user-supplied mass matrix approximation function.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_MASSMEM_NULL – the mass matrix solver memory was
NULL
.ARKLS_ILL_INPUT – an argument had an illegal value.
ARK_STEPPER_UNSUPPORTED – non-identity mass matrices are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support non-identity mass matrices.
This routine must be called after the ARKLS mass matrix solver interface has been initialized through a call to
ARKodeSetMassLinearSolver()
.Since there is no default difference quotient function for mass matrices, mass must be non-
NULL
.The function type
ARKLsMassFn()
is described in §2.4.4.Added in version 6.1.0.
-
int ARKodeSetLinearSolutionScaling(void *arkode_mem, sunbooleantype onoff)
Enables or disables scaling the linear system solution to account for a change in \(\gamma\) in the linear system. For more details see §10.2.1.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
onoff – flag to enable (
SUNTRUE
) or disable (SUNFALSE
) scaling.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_ILL_INPUT – the attached linear solver is not matrix-based.
ARK_STEPPER_UNSUPPORTED – implicit solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
Linear solution scaling is enabled by default when a matrix-based linear solver is attached.
Added in version 6.1.0.
2.4.3.8.4.3. Optional inputs for matrix-free 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 §2.2.15.2, when solving the Newton linear systems with matrix-free 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 Jacobian-times-vector approximation function, or use the default internal difference quotient function that comes with the ARKLS interface.
A user-defined Jacobian-vector function must be of type
ARKLsJacTimesVecFn
and can be specified through a call
to ARKodeSetJacTimes()
(see §2.4.4
for specification details). As with the
user-supplied preconditioner functions, the evaluation and
processing of any Jacobian-related data needed by the user’s
Jacobian-times-vector function is done in the optional user-supplied
function of type ARKLsJacTimesSetupFn
(see
§2.4.4 for specification details). As with
the preconditioner functions, a pointer to the user-defined
data structure, user_data, specified through
ARKodeSetUserData()
(or a NULL
pointer otherwise) is
passed to the Jacobian-times-vector setup and product functions each
time they are called.
-
int ARKodeSetJacTimes(void *arkode_mem, ARKLsJacTimesSetupFn jtsetup, ARKLsJacTimesVecFn jtimes)
Specifies the Jacobian-times-vector setup and product functions.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
jtsetup – user-defined Jacobian-vector setup function. Pass
NULL
if no setup is necessary.jtimes – user-defined Jacobian-vector product function.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_LMEM_NULL – the linear solver memory was
NULL
.ARKLS_ILL_INPUT – an input had an illegal value.
ARKLS_SUNLS_FAIL – an error occurred when setting up the Jacobian-vector product in the
SUNLinearSolver
object used by the ARKLS interface.ARK_STEPPER_UNSUPPORTED – implicit solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
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 non-NULL
jtimes andNULL
jtsetup inputs.This function must be called after the ARKLS system solver interface has been initialized through a call to
ARKodeSetLinearSolver()
.The function types
ARKLsJacTimesSetupFn
andARKLsJacTimesVecFn
are described in §2.4.4.Added in version 6.1.0.
When using the internal difference quotient the user may optionally supply
an alternative implicit right-hand side function for use in the Jacobian-vector
product approximation by calling ARKodeSetJacTimesRhsFn()
. The
alternative implicit right-hand side function should compute a suitable (and
differentiable) approximation to the \(f^I\) function provided to
*StepCreate
. For example, as done in [49],
the alternative function may use lagged values when evaluating a nonlinearity
in \(f^I\) to avoid differencing a potentially non-differentiable 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 ARKodeSetJacTimesRhsFn()
and
ARKodeSetNlsRhsFn()
.
-
int ARKodeSetJacTimesRhsFn(void *arkode_mem, ARKRhsFn jtimesRhsFn)
Specifies an alternative implicit right-hand side function for use in the internal Jacobian-vector product difference quotient approximation.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
jtimesRhsFn – the name of the C function (of type
ARKRhsFn()
) defining the alternative right-hand side function.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_LMEM_NULL – the linear solver memory was
NULL
.ARKLS_ILL_INPUT – an input had an illegal value.
ARK_STEPPER_UNSUPPORTED – implicit solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
The default is to use the implicit right-hand side function provided to
*StepCreate
in the internal difference quotient. If the input implicit right-hand 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
ARKodeSetLinearSolver()
.Added in version 6.1.0.
Similarly, if a problem involves a non-identity mass matrix,
\(M\ne I\), then matrix-free 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
user-supplied since there is no default value, it must be
of type ARKLsMassTimesVecFn()
, and can be specified
through a call to the ARKodeSetMassTimes()
routine.
Similarly to the user-supplied preconditioner functions, any evaluation
and processing of any mass matrix-related data needed by the user’s
mass-matrix-times-vector function may be done in an optional user-supplied
function of type ARKLsMassTimesSetupFn
(see
§2.4.4 for specification details).
-
int ARKodeSetMassTimes(void *arkode_mem, ARKLsMassTimesSetupFn mtsetup, ARKLsMassTimesVecFn mtimes, void *mtimes_data)
Specifies the mass matrix-times-vector setup and product functions.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
mtsetup – user-defined mass matrix-vector setup function. Pass
NULL
if no setup is necessary.mtimes – user-defined mass matrix-vector product function.
mtimes_data – a pointer to user data, that will be supplied to both the mtsetup and mtimes functions.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_MASSMEM_NULL – the mass matrix solver memory was
NULL
.ARKLS_ILL_INPUT – an input had an illegal value.
ARKLS_SUNLS_FAIL – an error occurred when setting up the mass-matrix-vector product in the
SUNLinearSolver
object used by the ARKLS interface.ARK_STEPPER_UNSUPPORTED – non-identity mass matrices are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support non-identity mass matrices.
There is no default finite difference quotient for mtimes, so if using the ARKLS mass matrix solver interface with NULL-valued SUNMATRIX input \(M\), and this routine is called with NULL-valued 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
ARKodeSetMassLinearSolver()
.The function types
ARKLsMassTimesSetupFn
andARKLsMassTimesVecFn
are described in §2.4.4.Added in version 6.1.0.
2.4.3.8.4.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 §2.2.15.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 user-supplied functions, psetup and psolve, that are supplied
to ARKODE using either the function
ARKodeSetPreconditioner()
(for preconditioning the
Newton system), or the function
ARKodeSetMassPreconditioner()
(for preconditioning the
mass matrix system). The psetup function supplied to these routines
should handle evaluation and preprocessing of any Jacobian or
mass-matrix data needed by the user’s preconditioner solve function,
psolve. The user data pointer received through
ARKodeSetUserData()
(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 user-supplied 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 §2.2.15.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 ARKodeSetEpsLin()
function.
-
int ARKodeSetPreconditioner(void *arkode_mem, ARKLsPrecSetupFn psetup, ARKLsPrecSolveFn psolve)
Specifies the user-supplied preconditioner setup and solve functions.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
psetup – user defined preconditioner setup function. Pass
NULL
if no setup is needed.psolve – user-defined preconditioner solve function.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_LMEM_NULL – the linear solver memory was
NULL
.ARKLS_ILL_INPUT – an input had an illegal value.
ARKLS_SUNLS_FAIL – an error occurred when setting up preconditioning in the
SUNLinearSolver
object used by the ARKLS interface.ARK_STEPPER_UNSUPPORTED – implicit solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
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
ARKodeSetLinearSolver()
.Both of the function types
ARKLsPrecSetupFn()
andARKLsPrecSolveFn()
are described in §2.4.4.Added in version 6.1.0.
-
int ARKodeSetMassPreconditioner(void *arkode_mem, ARKLsMassPrecSetupFn psetup, ARKLsMassPrecSolveFn psolve)
Specifies the mass matrix preconditioner setup and solve functions.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
psetup – user defined preconditioner setup function. Pass
NULL
if no setup is to be done.psolve – user-defined preconditioner solve function.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_LMEM_NULL – the linear solver memory was
NULL
.ARKLS_ILL_INPUT – an input had an illegal value.
ARKLS_SUNLS_FAIL – an error occurred when setting up preconditioning in the
SUNLinearSolver
object used by the ARKLS interface.ARK_STEPPER_UNSUPPORTED – non-identity mass matrices are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support non-identity mass matrices.
This function must be called after the ARKLS mass matrix solver interface has been initialized through a call to
ARKodeSetMassLinearSolver()
.The default is
NULL
for both arguments (i.e. no preconditioning).Both of the function types
ARKLsMassPrecSetupFn()
andARKLsMassPrecSolveFn()
are described in §2.4.4.Added in version 6.1.0.
-
int ARKodeSetEpsLin(void *arkode_mem, sunrealtype eplifac)
Specifies the factor \(\epsilon_L\) by which the tolerance on the nonlinear iteration is multiplied to get a tolerance on the linear iteration.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
eplifac – linear convergence safety factor.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_LMEM_NULL – the linear solver memory was
NULL
.ARKLS_ILL_INPUT – an input had an illegal value.
ARK_STEPPER_UNSUPPORTED – implicit solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
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
ARKodeSetLinearSolver()
.Added in version 6.1.0.
-
int ARKodeSetMassEpsLin(void *arkode_mem, sunrealtype eplifac)
Specifies the factor by which the tolerance on the nonlinear iteration is multiplied to get a tolerance on the mass matrix linear iteration.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
eplifac – linear convergence safety factor.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_MASSMEM_NULL – the mass matrix solver memory was
NULL
.ARKLS_ILL_INPUT – an input had an illegal value.
ARK_STEPPER_UNSUPPORTED – non-identity mass matrices are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support non-identity mass matrices.
This function must be called after the ARKLS mass matrix solver interface has been initialized through a call to
ARKodeSetMassLinearSolver()
.Passing a value eplifac \(\le 0\) indicates to use the default value of 0.05.
Added in version 6.1.0.
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 (2.28), 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 ARKodeSetLSNormFactor()
and ARKodeSetMassLSNormFactor()
allow for additional user control over these conversion factors.
-
int ARKodeSetLSNormFactor(void *arkode_mem, sunrealtype 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.
- Parameters:
arkode_mem – pointer to the ARKODE 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 values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_STEPPER_UNSUPPORTED – implicit solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
This function must be called after the ARKLS system solver interface has been initialized through a call to
ARKodeSetLinearSolver()
.Added in version 6.1.0.
-
int ARKodeSetMassLSNormFactor(void *arkode_mem, sunrealtype 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.
- Parameters:
arkode_mem – pointer to the ARKODE 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 values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_STEPPER_UNSUPPORTED – non-identity mass matrices are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support non-identity mass matrices.
This function must be called after the ARKLS mass matrix solver interface has been initialized through a call to
ARKodeSetMassLinearSolver()
.Added in version 6.1.0.
2.4.3.8.5. Rootfinding optional input functions
The following functions can be called to set optional inputs to control the rootfinding algorithm, the mathematics of which are described in §2.2.16.
Optional input |
Function name |
Default |
---|---|---|
Direction of zero-crossings to monitor |
both |
|
Disable inactive root warnings |
enabled |
-
int ARKodeSetRootDirection(void *arkode_mem, int *rootdir)
Specifies the direction of zero-crossings to be located and returned.
- Parameters:
arkode_mem – pointer to the ARKODE 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
ARKodeRootInit()
). Ifrootdir[i] == 0
then crossing in either direction for \(g_i\) should be reported. A value of +1 or -1 indicates that the solver should report only zero-crossings where \(g_i\) is increasing or decreasing, respectively.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an argument had an illegal value.
Note
The default behavior is to monitor for both zero-crossing directions.
Added in version 6.1.0.
-
int ARKodeSetNoInactiveRootWarn(void *arkode_mem)
Disables issuing a warning if some root function appears to be identically zero at the beginning of the integration.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.
Note
ARKODE will not report the initial conditions as a possible zero-crossing (assuming that one or more components \(g_i\) are zero at the initial time). However, if it appears that some \(g_i\) is identically zero at the initial time (i.e., \(g_i\) is zero at the initial time and after the first step), ARKODE will issue a warning which can be disabled with this optional input function.
Added in version 6.1.0.
2.4.3.9. Interpolated output function
An optional function ARKodeGetDky()
is available to obtain
additional values of solution-related quantities. This function
should only be called after a successful return from
ARKodeEvolve()
, 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 ARKodeEvolve()
. Internally, this “dense output” or
“continuous extension” algorithm is identical to the algorithm used for
the maximum order implicit predictors, described in
§2.2.15.5.2, except that derivatives of the
polynomial model may be evaluated upon request.
-
int ARKodeGetDky(void *arkode_mem, sunrealtype t, int k, N_Vector dky)
Computes the k-th derivative of the function \(y\) at the time t, i.e. \(y^{(k)}(t)\), for values of the independent variable satisfying \(t_n-h_n \le t \le t_n\), with \(t_n\) as current internal time reached, and \(h_n\) is the last internal step size successfully used by the solver. This routine uses an interpolating polynomial of degree min(degree, 5), where degree is the argument provided to
ARKodeSetInterpolantDegree()
. The user may request k in the range {0,…, min(degree, kmax)} where kmax depends on the choice of interpolation module. For Hermite interpolants kmax = 5 and for Lagrange interpolants kmax = 3.- Parameters:
arkode_mem – pointer to the ARKODE memory block.
t – the value of the independent variable at which the derivative is to be evaluated.
k – the derivative order requested.
dky – output vector (must be allocated by the user).
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_BAD_K – k is not in the range {0,…, min(degree, kmax)}.
ARK_BAD_T – t is not in the interval \([t_n-h_n, t_n]\).
ARK_BAD_DKY – the dky vector was
NULL
.ARK_MEM_NULL –
arkode_mem
wasNULL
.
Note
It is only legal to call this function after a successful return from
ARKodeEvolve()
.A user may access the values \(t_n\) and \(h_n\) via the functions
ARKodeGetCurrentTime()
andARKodeGetLastStep()
, respectively.Added in version 6.1.0.
2.4.3.10. Optional output functions
ARKODE provides an extensive set of functions that can be used to obtain solver performance information. We organize these into groups:
General ARKODE output routines are in §2.4.3.10.1,
ARKODE implicit solver output routines are in §2.4.3.10.2,
Output routines regarding root-finding results are in §2.4.3.10.3,
Linear solver output routines are in §2.4.3.10.4 and
General usability routines (e.g. to print the current ARKODE parameters, or output the current Butcher table(s)) are in §2.4.3.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 ARKODE. 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 user-supplied Jacobian or Jacobian-vector product routine than for the difference-quotient routine, it can indicate that the user-supplied Jacobian is inaccurate.
The ratio expsteps/accsteps can measure the quality of the ImEx splitting used, since a higher-quality splitting will be dominated by accuracy-limited 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.
2.4.3.10.1. Main solver optional output functions
Optional output |
Function name |
---|---|
Size of ARKODE 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 |
|
Integration direction, e.g., forward or backward |
|
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 stability-limited steps |
|
No. of accuracy-limited steps |
|
No. of attempted steps |
|
No. of RHS evaluations |
|
No. of local error test failures that have occurred |
|
No. of failed steps due to a nonlinear solver failure |
|
Estimated local truncation error vector |
|
Number of constraint test failures |
|
Retrieve a pointer for user data |
|
Retrieve the accumulated temporal error estimate |
-
int ARKodeGetWorkSpace(void *arkode_mem, long int *lenrw, long int *leniw)
Returns the ARKODE real and integer workspace sizes.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
lenrw – the number of
sunrealtype
values in the ARKODE workspace.leniw – the number of integer values in the ARKODE workspace.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.
Added in version 6.1.0.
-
int ARKodeGetNumSteps(void *arkode_mem, long int *nsteps)
Returns the cumulative number of internal steps taken by the solver (so far).
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
nsteps – number of steps taken in the solver.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.
Added in version 6.1.0.
-
int ARKodeGetActualInitStep(void *arkode_mem, sunrealtype *hinused)
Returns the value of the integration step size used on the first step.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
hinused – actual value of initial step size.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.
Note
Even if the value of the initial integration step was specified by the user through a call to
ARKodeSetInitStep()
, this value may have been changed by ARKODE 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.Added in version 6.1.0.
-
int ARKodeGetLastStep(void *arkode_mem, sunrealtype *hlast)
Returns the integration step size taken on the last successful internal step.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
hlast – step size taken on the last internal step.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.
Added in version 6.1.0.
-
int ARKodeGetCurrentStep(void *arkode_mem, sunrealtype *hcur)
Returns the integration step size to be attempted on the next internal step.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
hcur – step size to be attempted on the next internal step.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.
Added in version 6.1.0.
-
int ARKodeGetStepDirection(void *arkode_mem, sunrealtype *stepdir)
Returns the direction of integration that will be used on the next internal step.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
stepdir – a positive number if integrating forward, a negative number if integrating backward, or zero if the direction has not been set.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.
Added in version 6.2.0.
-
int ARKodeGetCurrentTime(void *arkode_mem, sunrealtype *tcur)
Returns the current internal time reached by the solver.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
tcur – current internal time reached.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.
Added in version 6.1.0.
-
int ARKodeGetCurrentState(void *arkode_mem, N_Vector *ycur)
Returns the current internal solution reached by the solver.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
ycur – current internal solution.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.
Note
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.
Added in version 6.1.0.
-
int ARKodeGetCurrentGamma(void *arkode_mem, sunrealtype *gamma)
Returns the current internal value of \(\gamma\) used in the implicit solver Newton matrix (see equation (2.51)).
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
gamma – current step size scaling factor in the Newton system.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_STEPPER_UNSUPPORTED – implicit solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
Added in version 6.1.0.
-
int ARKodeGetTolScaleFactor(void *arkode_mem, sunrealtype *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.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
tolsfac – suggested scaling factor for user-supplied tolerances.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.
Added in version 6.1.0.
-
int ARKodeGetErrWeights(void *arkode_mem, N_Vector eweight)
Returns the current error weight vector.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
eweight – solution error weights at the current time.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.
Note
The user must allocate space for eweight, that will be filled in by this function.
Added in version 6.1.0.
-
int ARKodeGetResWeights(void *arkode_mem, N_Vector rweight)
Returns the current residual weight vector.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
rweight – residual error weights at the current time.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_STEPPER_UNSUPPORTED – non-identity mass matrices are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support non-identity mass matrices.
The user must allocate space for rweight, that will be filled in by this function.
Added in version 6.1.0.
-
int ARKodeGetStepStats(void *arkode_mem, long int *nsteps, sunrealtype *hinused, sunrealtype *hlast, sunrealtype *hcur, sunrealtype *tcur)
Returns many of the most useful optional outputs in a single call.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
nsteps – number of steps taken in the solver.
hinused – actual value of initial step size.
hlast – step size taken on the last internal step.
hcur – step size to be attempted on the next internal step.
tcur – current internal time reached.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.
Added in version 6.1.0.
-
int ARKodePrintAllStats(void *arkode_mem, FILE *outfile, SUNOutputFormat fmt)
Outputs all of the integrator, nonlinear solver, linear solver, and other statistics.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
outfile – pointer to output file.
fmt –
the output format:
SUN_OUTPUTFORMAT_TABLE
– prints a table of valuesSUN_OUTPUTFORMAT_CSV
– prints a comma-separated list of key and value pairs e.g.,key1,value1,key2,value2,...
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_ILL_INPUT – an invalid formatting option was provided.
Note
The Python module
tools/suntools
provides utilities to read and output the data from a SUNDIALS CSV output file using the key and value pair format.Added in version 6.1.0.
-
char *ARKodeGetReturnFlagName(long int flag)
Returns the name of the ARKODE constant corresponding to flag. See ARKODE Constants.
- Parameters:
flag – a return flag from an ARKODE function.
- Returns:
The return value is a string containing the name of the corresponding constant.
Added in version 6.1.0.
-
int ARKodeGetNumExpSteps(void *arkode_mem, long int *expsteps)
Returns the cumulative number of stability-limited steps taken by the solver (so far). If the combination of the maximum number of stages and the current time step size in the LSRKStep module will not allow for a stable step, the counter also accounts for such returns.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
expsteps – number of stability-limited steps taken in the solver.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_STEPPER_UNSUPPORTED – adaptive step sizes are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support temporal adaptivity.
Added in version 6.1.0.
-
int ARKodeGetNumAccSteps(void *arkode_mem, long int *accsteps)
Returns the cumulative number of accuracy-limited steps taken by the solver (so far).
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
accsteps – number of accuracy-limited steps taken in the solver.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_STEPPER_UNSUPPORTED – adaptive step sizes are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support temporal adaptivity.
Added in version 6.1.0.
-
int ARKodeGetNumStepAttempts(void *arkode_mem, long int *step_attempts)
Returns the cumulative number of steps attempted by the solver (so far).
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
step_attempts – number of steps attempted by solver.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.
Added in version 6.1.0.
-
int ARKodeGetNumRhsEvals(void *arkode_mem, int partition_index, long int *num_rhs_evals)
Returns the number of calls to the user’s right-hand side function (so far). For implicit methods or methods with an implicit partition, the count does not include calls made by a linear solver or preconditioner.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
num_partition –
the right-hand side partition index:
For ERKStep,
0
corresponds to \(f(t,y)\)For ARKStep,
0
corresponds to \(f^E(t,y)\) and1
to \(f^I(t,y)\)For MRIStep,
0
corresponds to \(f^E(t,y)\) and1
to \(f^I(t,y)\)For SPRKStep,
0
corresponds to \(f_1(t,p)\) and1
to \(f_2(t,q)\)
A negative index will return the sum of the evaluations for each partition.
num_rhs_evals – the number of right-hand side evaluations.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL – if
arkode_mem
wasNULL
.ARK_ILL_INPUT – if
num_partiton
was invalid for the stepper ornum_rhs_evals
wasNULL
Added in version 6.2.0.
-
int ARKodeGetNumErrTestFails(void *arkode_mem, long int *netfails)
Returns the number of local error test failures that have occurred (so far).
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
netfails – number of error test failures.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.
Note
This is only compatible with time-stepping modules that support temporal adaptivity.
Added in version 6.1.0.
-
int ARKodeGetNumStepSolveFails(void *arkode_mem, long int *ncnf)
Returns the number of failed steps due to a nonlinear solver failure (so far).
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
ncnf – number of step failures.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_STEPPER_UNSUPPORTED – implicit solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
Added in version 6.1.0.
-
int ARKodeGetEstLocalErrors(void *arkode_mem, N_Vector ele)
Returns the vector of estimated local truncation errors for the current step.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
ele – vector of estimated local truncation errors.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.
Note
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
ARKodeEvolve()
(i.e., it returned a non-negative value).The ele vector, together with the eweight vector from
ARKodeGetErrWeights()
, 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]
.Added in version 6.1.0.
-
int ARKodeGetNumConstrFails(void *arkode_mem, long int *nconstrfails)
Returns the cumulative number of constraint test failures (so far).
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
nconstrfails – number of constraint test failures.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_STEPPER_UNSUPPORTED – adaptive step sizes are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support temporal adaptivity.
Added in version 6.1.0.
-
int ARKodeGetUserData(void *arkode_mem, void **user_data)
Returns the user data pointer previously set with
ARKodeSetUserData()
.- Parameters:
arkode_mem – pointer to the ARKODE memory block.
user_data – memory reference to a user data pointer.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.
Added in version 6.1.0.
-
int ARKodeGetAccumulatedError(void *arkode_mem, sunrealtype *accum_error)
Returns the accumulated temporal error estimate.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
accum_error – pointer to accumulated error estimate.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_WARNING – accumulated error estimation is currently disabled.
ARK_STEPPER_UNSUPPORTED – temporal error estimation is not supported by the current time-stepping module.
Added in version 6.2.0.
2.4.3.10.2. Implicit solver optional output functions
Optional output |
Function name |
---|---|
Computes state given a correction |
|
Access data to compute the nonlin. sys. function |
|
No. of calls to linear solver setup function |
|
No. of nonlinear solver iterations |
|
No. of nonlinear solver iterations |
|
No. of nonlinear solver convergence failures |
|
Single accessor to all nonlinear solver statistics |
-
int ARKodeGetNumLinSolvSetups(void *arkode_mem, long int *nlinsetups)
Returns the number of calls made to the linear solver’s setup routine (so far).
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
nlinsetups – number of linear solver setup calls made.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_STEPPER_UNSUPPORTED – linear solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
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 ARKODE, or when ARKODE is resized.
Added in version 6.1.0.
-
int ARKodeGetNumNonlinSolvIters(void *arkode_mem, long int *nniters)
Returns the number of nonlinear solver iterations performed (so far).
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
nniters – number of nonlinear iterations performed.
- Return values:
ARK_STEPPER_UNSUPPORTED – nonlinear solvers are not supported by the current time-stepping module.
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_NLS_OP_ERR – the SUNNONLINSOL object returned a failure flag.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
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 ARKODE, or when ARKODE is resized.
Added in version 6.1.0.
-
int ARKodeGetNumNonlinSolvConvFails(void *arkode_mem, long int *nncfails)
Returns the number of nonlinear solver convergence failures that have occurred (so far).
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
nncfails – number of nonlinear convergence failures.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_STEPPER_UNSUPPORTED – nonlinear solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
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 ARKODE, or when ARKODE is resized.
Added in version 6.1.0.
-
int ARKodeGetNonlinSolvStats(void *arkode_mem, long int *nniters, long int *nncfails)
Returns all of the nonlinear solver statistics in a single call.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
nniters – number of nonlinear iterations performed.
nncfails – number of nonlinear convergence failures.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_NLS_OP_ERR – the SUNNONLINSOL object returned a failure flag.
ARK_STEPPER_UNSUPPORTED – nonlinear solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
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 ARKODE, or when ARKODE is resized.
Added in version 6.1.0.
2.4.3.10.3. Rootfinding optional output functions
Optional output |
Function name |
---|---|
Array showing roots found |
|
No. of calls to user root function |
-
int ARKodeGetRootInfo(void *arkode_mem, int *rootsfound)
Returns an array showing which functions were found to have a root.
- Parameters:
arkode_mem – pointer to the ARKODE 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
ARKodeRootInit()
). For \(i = 0 \ldots\) nrtfn-1,rootsfound[i]
is nonzero if \(g_i\) has a root, and 0 if not.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.
Note
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 zero-crossing. A value of +1 indicates that \(g_i\) is increasing, while a value of -1 indicates a decreasing \(g_i\).Added in version 6.1.0.
-
int ARKodeGetNumGEvals(void *arkode_mem, long int *ngevals)
Returns the cumulative number of calls made to the user’s root function \(g\).
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
ngevals – number of calls made to \(g\) so far.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.
Added in version 6.1.0.
2.4.3.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 Jacobian-vector setup evaluations |
|
No. of Jacobian-vector 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 mass-matrix-vector setup evaluations |
|
Last return from a mass matrix solver function |
-
int ARKodeGetJac(void *arkode_mem, SUNMatrix *J)
Returns the internally stored copy of the Jacobian matrix of the ODE implicit right-hand side function.
- Parameters:
arkode_mem – the ARKODE 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.
ARK_STEPPER_UNSUPPORTED – linear solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
Warning
This function is provided for debugging purposes and the values in the returned matrix should not be altered.
Added in version 6.1.0.
-
int ARKodeGetJacTime(void *arkode_mem, sunrealtype *t_J)
Returns the time at which the internally stored copy of the Jacobian matrix of the ODE implicit right-hand side function was evaluated.
- Parameters:
arkode_mem – the ARKODE 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.
ARK_STEPPER_UNSUPPORTED – linear solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
-
int ARKodeGetJacNumSteps(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 right-hand side function was evaluated.
- Parameters:
arkode_mem – the ARKODE 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.
ARK_STEPPER_UNSUPPORTED – linear solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
Added in version 6.1.0.
-
int ARKodeGetLinWorkSpace(void *arkode_mem, long int *lenrwLS, long int *leniwLS)
Returns the real and integer workspace used by the ARKLS linear solver interface.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
lenrwLS – the number of
sunrealtype
values in the ARKLS workspace.leniwLS – the number of integer values in the ARKLS workspace.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_LMEM_NULL – the linear solver memory was
NULL
.ARK_STEPPER_UNSUPPORTED – linear solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
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).
Added in version 6.1.0.
-
int ARKodeGetNumJacEvals(void *arkode_mem, long int *njevals)
Returns the number of Jacobian evaluations.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
njevals – number of Jacobian evaluations.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_LMEM_NULL – the linear solver memory was
NULL
.ARK_STEPPER_UNSUPPORTED – linear solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
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 ARKODE, or when ARKODE is resized.
Added in version 6.1.0.
-
int ARKodeGetNumPrecEvals(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
.- Parameters:
arkode_mem – pointer to the ARKODE memory block.
npevals – the current number of calls to psetup.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_LMEM_NULL – the linear solver memory was
NULL
.ARK_STEPPER_UNSUPPORTED – linear solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
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 ARKODE, or when ARKODE is resized.
Added in version 6.1.0.
-
int ARKodeGetNumPrecSolves(void *arkode_mem, long int *npsolves)
Returns the number of calls made to the preconditioner solve function, psolve.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
npsolves – the number of calls to psolve.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_LMEM_NULL – the linear solver memory was
NULL
.ARK_STEPPER_UNSUPPORTED – linear solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
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 ARKODE, or when ARKODE is resized.
Added in version 6.1.0.
-
int ARKodeGetNumLinIters(void *arkode_mem, long int *nliters)
Returns the cumulative number of linear iterations.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
nliters – the current number of linear iterations.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_LMEM_NULL – the linear solver memory was
NULL
.ARK_STEPPER_UNSUPPORTED – linear solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
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 ARKODE, or when ARKODE is resized.
Added in version 6.1.0.
-
int ARKodeGetNumLinConvFails(void *arkode_mem, long int *nlcfails)
Returns the cumulative number of linear convergence failures.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
nlcfails – the current number of linear convergence failures.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_LMEM_NULL – the linear solver memory was
NULL
.ARK_STEPPER_UNSUPPORTED – linear solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
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 ARKODE, or when ARKODE is resized.
Added in version 6.1.0.
-
int ARKodeGetNumJTSetupEvals(void *arkode_mem, long int *njtsetup)
Returns the cumulative number of calls made to the user-supplied Jacobian-vector setup function, jtsetup.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
njtsetup – the current number of calls to jtsetup.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_LMEM_NULL – the linear solver memory was
NULL
.ARK_STEPPER_UNSUPPORTED – linear solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
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 ARKODE, or when ARKODE is resized.
Added in version 6.1.0.
-
int ARKodeGetNumJtimesEvals(void *arkode_mem, long int *njvevals)
Returns the cumulative number of calls made to the Jacobian-vector product function, jtimes.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
njvevals – the current number of calls to jtimes.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_LMEM_NULL – the linear solver memory was
NULL
.ARK_STEPPER_UNSUPPORTED – linear solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
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 ARKODE, or when ARKODE is resized.
Added in version 6.1.0.
-
int ARKodeGetNumLinRhsEvals(void *arkode_mem, long int *nfevalsLS)
Returns the number of calls to the user-supplied implicit right-hand side function \(f^I\) for finite difference Jacobian or Jacobian-vector product approximation.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
nfevalsLS – the number of calls to the user implicit right-hand side function.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_LMEM_NULL – the linear solver memory was
NULL
.ARK_STEPPER_UNSUPPORTED – linear solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
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 ARKODE, or when ARKODE is resized.
Added in version 6.1.0.
-
int ARKodeGetLastLinFlag(void *arkode_mem, long int *lsflag)
Returns the last return value from an ARKLS routine.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
lsflag – the value of the last return flag from an ARKLS function.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_LMEM_NULL – the linear solver memory was
NULL
.ARK_STEPPER_UNSUPPORTED – linear solvers are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
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 (
ARKodeEvolve()
returned ARK_LSETUP_FAIL), then lsflag will be SUNLS_PSET_FAIL_UNREC, SUNLS_ASET_FAIL_UNREC or SUN_ERR_EXT_FAIL.If the ARKLS solve function failed (
ARKodeEvolve()
returned ARK_LSOLVE_FAIL), then lsflag contains the error return flag from theSUNLinearSolver
object, which will be one of: SUN_ERR_ARG_CORRUPTRRUPT, indicating that theSUNLinearSolver
memory isNULL
; SUNLS_ATIMES_NULL, indicating that a matrix-free iterative solver was provided, but is missing a routine for the matrix-vector 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 Gram-Schmidt 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 SUN_ERR_EXT_FAIL, indicating an unrecoverable failure in an external iterative linear solver package.Added in version 6.1.0.
-
char *ARKodeGetLinReturnFlagName(long int lsflag)
Returns the name of the ARKLS constant corresponding to lsflag.
- Parameters:
lsflag – a return flag from an ARKLS function.
- Returns:
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”.
Note
This is only compatible with time-stepping modules that support implicit algebraic solvers.
Added in version 6.1.0.
-
int ARKodeGetMassWorkSpace(void *arkode_mem, long int *lenrwMLS, long int *leniwMLS)
Returns the real and integer workspace used by the ARKLS mass matrix linear solver interface.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
lenrwMLS – the number of
sunrealtype
values in the ARKLS mass solver workspace.leniwMLS – the number of integer values in the ARKLS mass solver workspace.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_LMEM_NULL – the linear solver memory was
NULL
.ARK_STEPPER_UNSUPPORTED – non-identity mass matrices are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support non-identity mass matrices.
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).
Added in version 6.1.0.
-
int ARKodeGetNumMassSetups(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 user-supplied mass-matrix constructor function.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
nmsetups – number of calls to the mass matrix solver setup routine.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_LMEM_NULL – the linear solver memory was
NULL
.ARK_STEPPER_UNSUPPORTED – non-identity mass matrices are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support non-identity mass matrices.
This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new mass-matrix linear solver module is “attached” to ARKODE, or when ARKODE is resized.
Added in version 6.1.0.
-
int ARKodeGetNumMassMultSetups(void *arkode_mem, long int *nmvsetups)
Returns the number of calls made to the ARKLS mass matrix ‘matvec setup’ (matrix-based solvers) routine.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
nmvsetups – number of calls to the mass matrix matrix-times-vector setup routine.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_LMEM_NULL – the linear solver memory was
NULL
.ARK_STEPPER_UNSUPPORTED – non-identity mass matrices are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support non-identity mass matrices.
This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new mass-matrix linear solver module is “attached” to ARKODE, or when ARKODE is resized.
Added in version 6.1.0.
-
int ARKodeGetNumMassMult(void *arkode_mem, long int *nmmults)
Returns the number of calls made to the ARKLS mass matrix ‘matvec’ routine (matrix-based solvers) or the user-supplied mtimes routine (matris-free solvers).
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
nmmults – number of calls to the mass matrix solver matrix-times-vector routine.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_LMEM_NULL – the linear solver memory was
NULL
.ARK_STEPPER_UNSUPPORTED – non-identity mass matrices are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support non-identity mass matrices.
This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new mass-matrix linear solver module is “attached” to ARKODE, or when ARKODE is resized.
Added in version 6.1.0.
-
int ARKodeGetNumMassSolves(void *arkode_mem, long int *nmsolves)
Returns the number of calls made to the ARKLS mass matrix solver ‘solve’ routine.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
nmsolves – number of calls to the mass matrix solver solve routine.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_LMEM_NULL – the linear solver memory was
NULL
.ARK_STEPPER_UNSUPPORTED – non-identity mass matrices are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support non-identity mass matrices.
This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new mass-matrix linear solver module is “attached” to ARKODE, or when ARKODE is resized.
Added in version 6.1.0.
-
int ARKodeGetNumMassPrecEvals(void *arkode_mem, long int *nmpevals)
Returns the total number of mass matrix preconditioner evaluations, i.e. the number of calls made to psetup.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
nmpevals – the current number of calls to psetup.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_LMEM_NULL – the linear solver memory was
NULL
.ARK_STEPPER_UNSUPPORTED – non-identity mass matrices are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support non-identity mass matrices.
This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new mass-matrix linear solver module is “attached” to ARKODE, or when ARKODE is resized.
Added in version 6.1.0.
-
int ARKodeGetNumMassPrecSolves(void *arkode_mem, long int *nmpsolves)
Returns the number of calls made to the mass matrix preconditioner solve function, psolve.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
nmpsolves – the number of calls to psolve.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_LMEM_NULL – the linear solver memory was
NULL
.ARK_STEPPER_UNSUPPORTED – non-identity mass matrices are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support non-identity mass matrices.
This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new mass-matrix linear solver module is “attached” to ARKODE, or when ARKODE is resized.
Added in version 6.1.0.
-
int ARKodeGetNumMassIters(void *arkode_mem, long int *nmiters)
Returns the cumulative number of mass matrix solver iterations.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
nmiters – the current number of mass matrix solver linear iterations.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_LMEM_NULL – the linear solver memory was
NULL
.ARK_STEPPER_UNSUPPORTED – non-identity mass matrices are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support non-identity mass matrices.
This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new mass-matrix linear solver module is “attached” to ARKODE, or when ARKODE is resized.
Added in version 6.1.0.
-
int ARKodeGetNumMassConvFails(void *arkode_mem, long int *nmcfails)
Returns the cumulative number of mass matrix solver convergence failures.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
nmcfails – the current number of mass matrix solver convergence failures.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_LMEM_NULL – the linear solver memory was
NULL
.ARK_STEPPER_UNSUPPORTED – non-identity mass matrices are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support non-identity mass matrices.
This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new mass-matrix linear solver module is “attached” to ARKODE, or when ARKODE is resized.
Added in version 6.1.0.
-
int ARKodeGetNumMTSetups(void *arkode_mem, long int *nmtsetup)
Returns the cumulative number of calls made to the user-supplied mass-matrix-vector product setup function, mtsetup.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
nmtsetup – the current number of calls to mtsetup.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_LMEM_NULL – the linear solver memory was
NULL
.ARK_STEPPER_UNSUPPORTED – non-identity mass matrices are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support non-identity mass matrices.
This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new mass-matrix linear solver module is “attached” to ARKODE, or when ARKODE is resized.
Added in version 6.1.0.
-
int ARKodeGetLastMassFlag(void *arkode_mem, long int *mlsflag)
Returns the last return value from an ARKLS mass matrix interface routine.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
mlsflag – the value of the last return flag from an ARKLS mass matrix solver interface function.
- Return values:
ARKLS_SUCCESS – the function exited successfully.
ARKLS_MEM_NULL –
arkode_mem
wasNULL
.ARKLS_LMEM_NULL – the linear solver memory was
NULL
.ARK_STEPPER_UNSUPPORTED – non-identity mass matrices are not supported by the current time-stepping module.
Note
This is only compatible with time-stepping modules that support non-identity mass matrices.
The values of msflag for each of the various solvers will match those described above for the function
ARKodeGetLastLinFlag()
.Added in version 6.1.0.
2.4.3.10.5. General usability functions
The following optional routine may be called by a user to inquire about existing solver parameters. While this would not typically be called during the course of solving an initial value problem, it may be useful for users wishing to better understand ARKODE.
Optional routine |
Function name |
---|---|
Output all ARKODE solver parameters |
-
int ARKodeWriteParameters(void *arkode_mem, FILE *fp)
Outputs all ARKODE solver parameters to the provided file pointer.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
fp – pointer to use for printing the solver parameters.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.
Note
The fp argument can be
stdout
orstderr
, or it may point to a specific file created usingfopen
.When run in parallel, only one process should set a non-NULL value for this pointer, since parameters for all processes would be identical.
Added in version 6.1.0.
2.4.3.11. ARKODE reset function
To reset the ARKODE module to a particular state \((t_R,y(t_R))\) for the
continued solution of a problem, where a prior
call to *StepCreate
has been made, the user must call the function
ARKodeReset()
. Like the stepper-specific *StepReInit
functions,
this routine retains the current settings for all solver options and
performs no memory allocations but, unlike *StepReInit
, this routine
performs only a subset of the input checking and initializations that are
done in *StepCreate
. 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 *StepReInit
, a call to
ARKodeReset()
will delete any previously-set tstop value specified
via a call to ARKodeSetStopTime()
. Following a successful call to
ARKodeReset()
, call ARKodeEvolve()
again to continue
solving the problem. By default the next call to ARKodeEvolve()
will
use the step size computed by ARKODE prior to calling ARKodeReset()
.
To set a different step size or have ARKODE estimate a new step size use
ARKodeSetInitStep()
.
One important use of the ARKodeReset()
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 ARKodeReset()
. 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 ARKodeReset(void *arkode_mem, sunrealtype tR, N_Vector yR)
Resets the current ARKODE time-stepper module state to the provided independent variable value and dependent variable vector.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
tR – the value of the independent variable \(t\).
yR – the value of the dependent variable vector \(y(t_R)\).
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_MEM_FAIL – a memory allocation failed.
ARK_ILL_INPUT – an argument had an illegal value.
Note
By default the next call to
ARKodeEvolve()
will use the step size computed by ARKODE prior to callingARKodeReset()
. To set a different step size or have ARKODE estimate a new step size useARKodeSetInitStep()
.All previously set options are retained but may be updated by calling the appropriate “Set” functions.
If an error occurred,
ARKodeReset()
also sends an error message to the error handler function.Added in version 6.1.0.
2.4.3.12. ARKODE system resize function
For simulations involving changes to the number of equations and
unknowns in the ODE system (e.g. when using spatially-adaptive
PDE simulations under a method-of-lines approach), the ARKODE
integrator may be “resized” between integration steps, through calls
to the ARKodeResize()
function. This function modifies
ARKODE’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 time-stepping heuristics prior
to calling ARKodeResize()
remain valid after the call. If
instead the dynamics should be recomputed from scratch, the ARKODE
memory structure should be deleted with a call to
ARKodeFree()
, and recreated with a calls to
*StepCreate
.
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 in-place 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 ARKODE will be destroyed and re-cloned 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 ARKodeResize(void *arkode_mem, N_Vector yR, sunrealtype hscale, sunrealtype tR, ARKVecResizeFn resize, void *resize_data)
Re-sizes ARKODE with a different state vector but with comparable dynamical time scale.
- Parameters:
arkode_mem – pointer to the ARKODE memory block.
yR – the newly-sized 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 user-supplied vector resize function (of type
ARKVecResizeFn()
.resize_data – the user-supplied data structure to be passed to resize when modifying internal ARKODE vectors.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_NULL –
arkode_mem
wasNULL
.ARK_NO_MALLOC –
arkode_mem
was not allocated.ARK_ILL_INPUT – an argument had an illegal value.
Note
If an error occurred,
ARKodeResize()
also sends an error message to the error handler function.If inequality constraint checking is enabled a call to
ARKodeResize()
will disable constraint checking. A call toARKodeSetConstraints()
is required to re-enable constraint checking.Resizing the linear solver:
When using any of the SUNDIALS-provided linear solver modules, the linear solver memory structures must also be resized. At present, none of these include a solver-specific “resize” function, so the linear solver memory must be destroyed and re-allocated following each call to
ARKodeResize()
. Moreover, the existing ARKLS interface should then be deleted and recreated by attaching the updatedSUNLinearSolver
(and possiblySUNMatrix
) object(s) through calls toARKodeSetLinearSolver()
, andARKodeSetMassLinearSolver()
.If any user-supplied routines are provided to aid the linear solver (e.g. Jacobian construction, Jacobian-vector product, mass-matrix-vector product, preconditioning), then the corresponding “set” routines must be called again following the solver re-specification.
Resizing the absolute tolerance array:
If using array-valued absolute tolerances, the absolute tolerance vector will be invalid after the call to
ARKodeResize()
, so the new absolute tolerance vector should be re-set following each call toARKodeResize()
through a new call toARKodeSVtolerances()
and possiblyARKodeResVtolerance()
if applicable.If scalar-valued tolerances or a tolerance function was specified through either
ARKodeSStolerances()
orARKodeWFtolerances()
, then these will remain valid and no further action is necessary.Example codes:
examples/arkode/C_serial/ark_heat1D_adapt.c
Added in version 6.1.0.
2.4.3.13. Using an ARKODE solver as an MRIStep “inner” solver
When using an integrator from ARKODE as the inner (fast) integrator with MRIStep, the
utility function ARKodeCreateMRIStepInnerStepper()
should be used to
wrap the ARKODE memory block as an MRIStepInnerStepper
.
-
int ARKodeCreateMRIStepInnerStepper(void *inner_arkode_mem, MRIStepInnerStepper *stepper)
Wraps an ARKODE integrator as an
MRIStepInnerStepper
for use with MRIStep.- Parameters:
arkode_mem – pointer to the ARKODE memory block.
stepper – the
MRIStepInnerStepper
object to create.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_FAIL – a memory allocation failed.
ARK_STEPPER_UNSUPPORTED – the time-stepping module does not currently support use as an inner stepper.
Note
Currently, ARKODE integrators based on ARKStep, ERKStep, and MRIStep support use as an MRIStep inner stepper.
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) object */ MRIStepInnerStepper stepper = NULL; /* create an ARKODE object, setting fast (inner) right-hand side functions and the initial condition */ inner_arkode_mem = *StepCreate(...); /* configure the inner integrator */ retval = ARKodeSet*(inner_arkode_mem, ...); /* create MRIStepInnerStepper wrapper for the ARKODE integrator */ flag = ARKodeCreateMRIStepInnerStepper(inner_arkode_mem, &stepper); /* create an MRIStep object, setting the slow (outer) right-hand side functions and the initial condition */ outer_arkode_mem = MRIStepCreate(fse, fsi, t0, y0, stepper, sunctx)
2.4.3.14. Using an ARKODE solver as a SUNStepper
The utility function ARKodeCreateSUNStepper()
wraps an ARKODE memory
block as a SUNStepper
.
-
int ARKodeCreateSUNStepper(void *inner_arkode_mem, SUNStepper *stepper)
Wraps an ARKODE integrator as a
SUNStepper
.- Parameters:
arkode_mem – pointer to the ARKODE memory block.
stepper – the
SUNStepper
object.
- Return values:
ARK_SUCCESS – the function exited successfully.
ARK_MEM_FAIL – a memory allocation failed.
ARK_SUNSTEPPER_ERR – the
SUNStepper
initialization failed.
Warning
Currently,
stepper
will be equipped with an implementation for theSUNStepper_SetForcing()
function only ifinner_arkode_mem
is an ARKStep, ERKStep, or MRIStep integrator.Added in version 6.2.0.