3.4.3.2. ERKStep User-callable functions

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

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

3.4.3.2.1. ERKStep initialization and deallocation functions

void *ERKStepCreate(ARKRhsFn f, sunrealtype t0, N_Vector y0, SUNContext sunctx)

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

Arguments:

f – the name of the C function (of type ARKRhsFn()) defining the right-hand side function in \(\dot{y} = f(t,y)\).
t0 – the initial value of \(t\).
y0 – the initial condition vector \(y(t_0)\).
sunctx – the SUNContext object (see §2.4)

Return value:

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

void ERKStepFree(void **arkode_mem)

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

Arguments:

arkode_mem – pointer to the ERKStep memory block.

Return value: None

3.4.3.2.2. ERKStep tolerance specification functions

These functions specify the integration tolerances. One of them should be called before the first call to ERKStepEvolve(); 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 ERKStepSStolerances(), this vector has components

ewt[i] = 1.0/(reltol*abs(y[i]) + abstol);

whereas in the case of ERKStepSVtolerances() the vector components are given by

ewt[i] = 1.0/(reltol*abs(y[i]) + abstol[i]);

This vector is used in all error tests, which use a weighted RMS norm on all error-like vectors v:

\[\|v\|_{WRMS} = \left( \frac{1}{N} \sum_{i=1}^N (v_i\; ewt_i)^2 \right)^{1/2},\]

where \(N\) is the problem dimension.

Alternatively, the user may supply a custom function to supply the ewt vector, through a call to ERKStepWFtolerances().

int ERKStepSStolerances(void *arkode_mem, sunrealtype reltol, sunrealtype abstol)

This function specifies scalar relative and absolute tolerances.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
reltol – scalar relative tolerance.
abstol – scalar absolute tolerance.

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ERKStep memory was NULL
ARK_NO_MALLOC if the ERKStep memory was not allocated by the time-stepping module
ARK_ILL_INPUT if an argument has an illegal value (e.g. a negative tolerance).

int ERKStepSVtolerances(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).

Arguments:

arkode_mem – pointer to the ERKStep memory block.
reltol – scalar relative tolerance.
abstol – vector containing the absolute tolerances for each solution component.

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ERKStep memory was NULL
ARK_NO_MALLOC if the ERKStep memory was not allocated by the time-stepping module
ARK_ILL_INPUT if an argument has an illegal value (e.g. a negative tolerance).

int ERKStepWFtolerances(void *arkode_mem, ARKEwtFn efun)

This function specifies a user-supplied function efun to compute the error weight vector ewt.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
efun – the name of the function (of type ARKEwtFn()) that implements the error weight vector computation.

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ERKStep memory was NULL
ARK_NO_MALLOC if the ERKStep memory was not allocated by the time-stepping module

3.4.3.2.2.1. General advice on the choice of tolerances

For many users, the appropriate choices for tolerance values in reltol and abstol are a concern. The following pieces of advice are relevant.

The scalar relative tolerance reltol is to be set to control relative errors. So a value of \(10^{-4}\) means that errors are controlled to .01%. We do not recommend using reltol larger than \(10^{-3}\). On the other hand, reltol should not be so small that it is comparable to the unit roundoff of the machine arithmetic (generally around \(10^{-15}\) for 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. Then abstol (if scalar) or abstol[i] (if a vector) needs to be set to that noise level. If the different components have different noise levels, then abstol should be a vector. For example, see the example problem ark_robertson.c, and the discussion of it in the ARKODE Examples Documentation [99]. In that problem, the three components vary between 0 and 1, and have different noise levels; hence the atols vector therein. It is impossible to give any general advice on abstol values, because the appropriate noise levels are completely problem-dependent. The user or modeler hopefully has some idea as to what those noise levels are.
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.

3.4.3.2.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 ERKStep, with magnitude comparable to abstol or less, is equivalent to zero as far as the computation is concerned.
The user’s right-hand side routine \(f\) 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\) routine 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(t, y)\).
ERKStep supports 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 ERKStepSetConstraints(). At each internal time step, if any constraint is violated then ERKStep will attempt a smaller time step that should not violate this constraint. This reduced step size is chosen such that the step size is the largest possible but where the solution component satisfies the constraint.
Positivity and non-negativity constraints on components can be enforced by use of the recoverable error return feature in the user-supplied right-hand side function, \(f\). When a recoverable error is encountered, ERKStep will retry the step with a smaller step size, which typically alleviates the problem. However, because this option involves some additional overhead cost, it should only be exercised if the use of absolute tolerances to control the computed values is unsuccessful.

3.4.3.2.3. Rootfinding initialization function

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

int ERKStepRootInit(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 ERKStepCreate(), and before ERKStepEvolve().

Arguments:

arkode_mem – pointer to the ERKStep 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 value:

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

Notes:

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

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

3.4.3.2.4. ERKStep solver function

This is the central step in the solution process – the call to perform the integration of the IVP. One of the input arguments (itask) specifies one of two modes as to where ERKStep 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 ERKStepSetStopTime()) or has requested rootfinding.

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

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

Arguments:

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

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

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

Return value:

ARK_SUCCESS if successful.
ARK_ROOT_RETURN if ERKStepEvolve() succeeded, and found one or more roots. If the number of root functions, nrtfn, is greater than 1, call ERKStepGetRootInfo() to see which \(g_i\) were found to have a root at (*tret).
ARK_TSTOP_RETURN if ERKStepEvolve() succeeded and returned at tstop.
ARK_MEM_NULL if the arkode_mem argument was NULL.
ARK_NO_MALLOC if arkode_mem was not allocated.
ARK_ILL_INPUT if one of the inputs to ERKStepEvolve() 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:
1. A component of the error weight vector became zero during internal time-stepping.
2. A root of one of the root functions was found both at a point \(t\) and also very near \(t\).
3. The initial condition violates the inequality constraints.
ARK_TOO_MUCH_WORK if the solver took mxstep internal steps but could not reach tout. The default value for mxstep is MXSTEP_DEFAULT = 500.
ARK_TOO_MUCH_ACC if the solver could not satisfy the accuracy demanded by the user for some internal step.
ARK_ERR_FAILURE if error test failures occurred either too many times (ark_maxnef) during one internal time step or occurred with \(|h| = h_{min}\).
ARK_VECTOROP_ERR a vector operation error occurred.

Notes:

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

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 ERKStepEvolve() failures.

Since interpolation may reduce the accuracy in the reported solution, if full method accuracy is desired the user should issue a call to ERKStepSetStopTime() before the call to ERKStepEvolve() to specify a fixed stop time to end the time step and return to the user. Upon return from ERKStepEvolve(), a copy of the internal solution \(y_{n}\) will be returned in the vector yout. Once the integrator returns at a tstop time, any future testing for tstop is disabled (and can be re-enabled only though a new call to ERKStepSetStopTime()).

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

3.4.3.2.5. Optional input functions

There are numerous optional input parameters that control the behavior of ERKStep, 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 ERKStep 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 ERKStep options (Table 3.3),
IVP method solver options (Table 3.4),
Step adaptivity solver options (Table 3.5), and
Rootfinding options (Table 3.6).

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

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

3.4.3.2.5.1. Optional inputs for ERKStep

Table 3.3 Optional inputs for ERKStep
Optional input	Function name	Default
Return ERKStep solver parameters to their defaults	`ERKStepSetDefaults()`	internal
Set dense output interpolation type	`ERKStepSetInterpolantType()`	`ARK_INTERP_HERMITE`
Set dense output polynomial degree	`ERKStepSetInterpolantDegree()`	5
Supply a pointer to a diagnostics output file	`ERKStepSetDiagnostics()`	`NULL`
Disable time step adaptivity (fixed-step mode)	`ERKStepSetFixedStep()`	disabled
Supply an initial step size to attempt	`ERKStepSetInitStep()`	estimated
Maximum no. of warnings for \(t_n+h = t_n\)	`ERKStepSetMaxHnilWarns()`	10
Maximum no. of internal steps before tout	`ERKStepSetMaxNumSteps()`	500
Maximum absolute step size	`ERKStepSetMaxStep()`	\(\infty\)
Minimum absolute step size	`ERKStepSetMinStep()`	0.0
Set a value for \(t_{stop}\)	`ERKStepSetStopTime()`	undefined
Interpolate at \(t_{stop}\)	`ERKStepInterpolateSetStopTime()`	`SUNFALSE`
Disable the stop time	`ERKStepClearStopTime()`	N/A
Supply a pointer for user data	`ERKStepSetUserData()`	`NULL`
Maximum no. of ERKStep error test failures	`ERKStepSetMaxErrTestFails()`	7
Set inequality constraints on solution	`ERKStepSetConstraints()`	`NULL`
Set max number of constraint failures	`ERKStepSetMaxNumConstrFails()`	10

int ERKStepSetDefaults(void *arkode_mem)

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

Arguments:

arkode_mem – pointer to the ERKStep memory block.

Return value:

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

Notes:

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

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

int ERKStepSetInterpolantType(void *arkode_mem, int itype)

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

Arguments:

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

Return value:

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

Notes:

The Hermite interpolation module is described in §3.2.2.1, and the Lagrange interpolation module is described in §3.2.2.2.

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

This routine must be called after the call to ERKStepCreate(). After the first call to ERKStepEvolve() the interpolation type may not be changed without first calling ERKStepReInit().

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

int ERKStepSetInterpolantDegree(void *arkode_mem, int degree)

Specifies the degree of the polynomial interpolant used for dense output (i.e. interpolation of solution output values and implicit method predictors).

Arguments:

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

Return value:

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

Notes:

Allowed values are between 0 and 5.

This routine should be called after ERKStepCreate() and before ERKStepEvolve(). After the first call to ERKStepEvolve() the interpolation degree may not be changed without first calling ERKStepReInit().

If a user calls both this routine and ERKStepSetInterpolantType(), then ERKStepSetInterpolantType() 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 ERKStep 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.

Changed in version 5.5.1: When \(q=1\), a linear interpolant is the default to ensure values obtained by the integrator are returned at the ends of the time interval.

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

int ERKStepSetDiagnostics(void *arkode_mem, FILE *diagfp)

Specifies the file pointer for a diagnostics file where all ERKStep step adaptivity and solver information is written.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
diagfp – pointer to the diagnostics output file.

Return value:

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

Notes:

This parameter can be stdout or stderr, although the suggested approach is to specify a pointer to a unique file opened by the user and returned by fopen. If not called, or if called with a NULL file pointer, all diagnostics output is disabled.

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

Deprecated since version 5.2.0: Use SUNLogger_SetInfoFilename() instead.

int ERKStepSetFixedStep(void *arkode_mem, sunrealtype hfixed)

Disabled time step adaptivity within ERKStep, and specifies the fixed time step size to use for the following internal step(s).

Arguments:

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

Return value:

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

Notes:

Pass 0.0 to return ERKStep to the default (adaptive-step) mode.

Use of this function is not generally recommended, since we it gives no assurance of the validity of the computed solutions. It is primarily provided for code-to-code verification testing purposes.

When using ERKStepSetFixedStep(), any values provided to the functions ERKStepSetInitStep(), ERKStepSetAdaptivityFn(), ERKStepSetMaxErrTestFails(), ERKStepSetAdaptivityMethod(), ERKStepSetCFLFraction(), ERKStepSetErrorBias(), ERKStepSetFixedStepBounds(), ERKStepSetMaxEFailGrowth(), ERKStepSetMaxFirstGrowth(), ERKStepSetMaxGrowth(), ERKStepSetMinReduction(), ERKStepSetSafetyFactor(), ERKStepSetSmallNumEFails(), ERKStepSetStabilityFn(), and ERKStepSetAdaptController() will be ignored, since temporal adaptivity is disabled.

If both ERKStepSetFixedStep() and ERKStepSetStopTime() 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 to ERKStepSetFixedStep() must be made prior to calling ERKStepEvolve() to resume integration.

It is not recommended that ERKStepSetFixedStep() be used in concert with ERKStepSetMaxStep() or ERKStepSetMinStep(), since at best those latter two routines will provide no useful information to the solver, and at worst they may interfere with the desired fixed step size.

int ERKStepSetInitStep(void *arkode_mem, sunrealtype hin)

Specifies the initial time step size ERKStep should use after initialization, re-initialization, or resetting.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
hin – value of the initial step to be attempted \((\ne 0)\).

Return value:

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

Notes:

Pass 0.0 to use the default value.

By default, ERKStep estimates the initial step size to be \(h = \sqrt{\dfrac{2}{\left\| \ddot{y} \right\|}}\), where \(\ddot{y}\) is an estimate of the second derivative of the solution at \(t_0\).

This routine will also reset the step size and error history.

int ERKStepSetMaxHnilWarns(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 ERKStep will instead return with an error.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
mxhnil – maximum allowed number of warning messages \((>0)\).

Return value:

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

Notes:

The default value is 10; set mxhnil to zero to specify this default.

A negative value indicates that no warning messages should be issued.

int ERKStepSetMaxNumSteps(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 ERKStep will return with an error.

Arguments:

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

Return value:

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

Notes:

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

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

int ERKStepSetMaxStep(void *arkode_mem, sunrealtype hmax)

Specifies the upper bound on the magnitude of the time step size.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
hmax – maximum absolute value of the time step size \((\ge 0)\).

Return value:

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

Notes:

Pass hmax \(\le 0.0\) to set the default value of \(\infty\).

int ERKStepSetMinStep(void *arkode_mem, sunrealtype hmin)

Specifies the lower bound on the magnitude of the time step size.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
hmin – minimum absolute value of the time step size \((\ge 0)\).

Return value:

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

Notes:

Pass hmin \(\le 0.0\) to set the default value of 0.

int ERKStepSetStopTime(void *arkode_mem, sunrealtype tstop)

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

Arguments:

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

Return value:

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

Notes:

The default is that no stop time is imposed.

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

A stop time not reached before a call to ERKStepReInit() or ERKStepReset() will remain active but can be disabled by calling ERKStepClearStopTime().

int ERKStepSetInterpolateStopTime(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\)).

Arguments:

arkode_mem – pointer to the ERKStep memory block.
interp – flag indicating to use interpolation (1) or copy (0).

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory is NULL

New in version 5.6.0.

int ERKStepClearStopTime(void *arkode_mem)

Disables the stop time set with ERKStepSetStopTime().

Arguments:

arkode_mem – pointer to the ERKStep memory block.

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ERKStep memory is NULL

Notes:

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

New in version 5.5.1.

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

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

Arguments:

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

Return value:

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

Notes:

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

int ERKStepSetMaxErrTestFails(void *arkode_mem, int maxnef)

Specifies the maximum number of error test failures permitted in attempting one step, before returning with an error.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
maxnef – maximum allowed number of error test failures \((>0)\).

Return value:

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

Notes:

The default value is 7; set maxnef \(\le 0\) to specify this default.

int ERKStepSetConstraints(void *arkode_mem, N_Vector constraints)

Specifies a vector defining inequality constraints for each component of the solution vector \(y\).

Arguments:

arkode_mem – pointer to the ERKStep memory block.
constraints – vector of constraint flags. Each component specifies the type of solution constraint:

\[\begin{split}\texttt{constraints[i]} = \left\{ \begin{array}{rcl} 0.0 &\Rightarrow\;& \text{no constraint is imposed on}\; y_i,\\ 1.0 &\Rightarrow\;& y_i \geq 0,\\ -1.0 &\Rightarrow\;& y_i \leq 0,\\ 2.0 &\Rightarrow\;& y_i > 0,\\ -2.0 &\Rightarrow\;& y_i < 0.\\ \end{array}\right.\end{split}\]

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ERKStep memory is NULL
ARK_ILL_INPUT if the constraints vector contains illegal values

Notes:

The presence of a non-NULL constraints vector that is not 0.0 in all components will cause constraint checking to be performed. However, a call with 0.0 in all components of constraints will result in an illegal input return. A NULL constraints vector will disable constraint checking.

After a call to ERKStepResize() inequality constraint checking will be disabled and a call to ERKStepSetConstraints() 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 ERKStepSetConstraints() and ERKStepSetFixedStep() are incompatible, and should not be used simultaneously.

int ERKStepSetMaxNumConstrFails(void *arkode_mem, int maxfails)

Specifies the maximum number of constraint failures in a step before ERKStep will return with an error.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
maxfails – maximum allowed number of constrain failures.

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ERKStep memory is NULL

Notes:

Passing maxfails <= 0 results in ERKStep using the default value (10).

3.4.3.2.5.2. Optional inputs for IVP method selection

Table 3.4 Optional inputs for IVP method selection
Optional input	Function name	Default
Set integrator method order	`ERKStepSetOrder()`	4
Set explicit RK table	`ERKStepSetTable()`	internal
Set explicit RK table via its number	`ERKStepSetTableNum()`	internal
Set explicit RK table via its name	`ERKStepSetTableName()`	internal

int ERKStepSetOrder(void *arkode_mem, int ord)

Specifies the order of accuracy for the ERK integration method.

Arguments:

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

Return value:

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

Notes:

The allowed values are \(2 \le\) ord \(\le 8\). Any illegal input will result in the default value of 4.

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

int ERKStepSetTable(void *arkode_mem, ARKodeButcherTable B)

Specifies a customized Butcher table for the ERK method.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
B – the Butcher table for the explicit RK method.

Return value:

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

Notes:

For a description of the ARKodeButcherTable type and related functions for creating Butcher tables, see §3.5.

No error checking is performed to ensure that either the method order p or the embedding order q specified in the Butcher table structure correctly describe the coefficients in the Butcher table.

Error checking is performed to ensure that the Butcher table is strictly lower-triangular (i.e. that it specifies an ERK method).

If the Butcher table does not contain an embedding, the user must call ERKStepSetFixedStep() to enable fixed-step mode and set the desired time step size.

int ERKStepSetTableNum(void *arkode_mem, ARKODE_ERKTableID etable)

Indicates to use a specific built-in Butcher table for the ERK method.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
etable – index of the Butcher table.

Return value:

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

Notes:

etable should match an existing explicit method from §3.8.1. Error-checking is performed to ensure that the table exists, and is not implicit.

int ERKStepSetTableName(void *arkode_mem, const char *etable)

Indicates to use a specific built-in Butcher table for the ERK method.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
etable – name of the Butcher table.

Return value:

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

Notes:

etable should match an existing explicit method from §3.8.1. Error-checking is performed to ensure that the table exists, and is not implicit. This function is case sensitive.

3.4.3.2.5.3. Optional inputs for time step adaptivity

The mathematical explanation of ARKODE’s time step adaptivity algorithm, including how each of the parameters below is used within the code, is provided in §3.2.8.

Table 3.5 Optional inputs for time step adaptivity
Optional input	Function name	Default
Provide a `SUNAdaptController` for ERKStep to use	`ERKStepSetAdaptController()`	PI
Set a custom time step adaptivity function	`ERKStepSetAdaptivityFn()`	internal
Choose an existing time step adaptivity method	`ERKStepSetAdaptivityMethod()`	0
Adjust the method order used in the controller	`ERKStepSetAdaptivityAdjustment()`	-1
Explicit stability safety factor	`ERKStepSetCFLFraction()`	0.5
Time step error bias factor	`ERKStepSetErrorBias()`	1.5
Bounds determining no change in step size	`ERKStepSetFixedStepBounds()`	1.0 1.5
Maximum step growth factor on error test fail	`ERKStepSetMaxEFailGrowth()`	0.3
Maximum first step growth factor	`ERKStepSetMaxFirstGrowth()`	10000.0
Maximum allowed general step growth factor	`ERKStepSetMaxGrowth()`	20.0
Minimum allowed step reduction factor on error test fail	`ERKStepSetMinReduction()`	0.1
Time step safety factor	`ERKStepSetSafetyFactor()`	0.96
Error fails before MaxEFailGrowth takes effect	`ERKStepSetSmallNumEFails()`	2
Explicit stability function	`ERKStepSetStabilityFn()`	none

int ERKStepSetAdaptController(void *arkode_mem, SUNAdaptController C)

Sets a user-supplied time-step controller object.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
C – user-supplied time adaptivity controller. If NULL then the PID controller will be created (see §13.2).

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ERKStep memory is NULL
ARK_MEM_FAIL if C was NULL and the PID controller could not be allocated.

Notes:

When C is NULL, the PID controller that is created is not the same as the ERKStep default (PI). To reset ERKStep to its default behavior after a non-default controller has been used, users should either specifically create the PI controller C and attach it here, or call ERKStepSetDefaults().

New in version 5.7.0.

int ERKStepSetAdaptivityFn(void *arkode_mem, ARKAdaptFn hfun, void *h_data)

Sets a user-supplied time-step adaptivity function.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
hfun – name of user-supplied adaptivity function.
h_data – pointer to user data passed to hfun every time it is called.

Return value:

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

Notes:

This function should focus on accuracy-based time step estimation; for stability based time steps the function ERKStepSetStabilityFn() should be used instead.

Deprecated since version 5.7.0: Use the SUNAdaptController infrastructure instead (see §13.1).

int ERKStepSetAdaptivityMethod(void *arkode_mem, int imethod, int idefault, int pq, sunrealtype *adapt_params)

Specifies the method (and associated parameters) used for time step adaptivity.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
imethod – accuracy-based adaptivity method choice (0 \(\le\) imethod \(\le\) 5): 0 is PID, 1 is PI, 2 is I, 3 is explicit Gustafsson, 4 is implicit Gustafsson, and 5 is the ImEx Gustafsson.
idefault – flag denoting whether to use default adaptivity parameters (1), or that they will be supplied in the adapt_params argument (0).
pq – flag denoting whether to use the embedding order of accuracy p (0), the method order of accuracy q (1), or the minimum of the two (any input not equal to 0 or 1) within the adaptivity algorithm. p is the default.
adapt_params[0] – \(k_1\) parameter within accuracy-based adaptivity algorithms.
adapt_params[1] – \(k_2\) parameter within accuracy-based adaptivity algorithms.
adapt_params[2] – \(k_3\) parameter within accuracy-based adaptivity algorithms.

Return value:

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

Notes:

If custom parameters are supplied, they will be checked for validity against published stability intervals. If other parameter values are desired, it is recommended to instead provide a custom function through a call to ERKStepSetAdaptivityFn().

Changed in version 5.7.0: Prior to version 5.7.0, any nonzero value for pq would result in use of the embedding order of accuracy.

Deprecated since version 5.7.0: Use the SUNAdaptController infrastructure instead (see §13.1).

int ERKStepSetAdaptivityAdjustment(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\).

Arguments:

arkode_mem – pointer to the ERKStep memory block.
adjust – adjustment factor (default is -1).

Return value:

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

Notes:

This should be called prior to calling ERKStepEvolve(), and can only be reset following a call to ERKStepReInit().

New in version 5.7.0.

int ERKStepSetCFLFraction(void *arkode_mem, sunrealtype cfl_frac)

Specifies the fraction of the estimated explicitly stable step to use.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
cfl_frac – maximum allowed fraction of explicitly stable step (default is 0.5).

Return value:

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

Notes:

Any non-positive parameter will imply a reset to the default value.

int ERKStepSetErrorBias(void *arkode_mem, sunrealtype bias)

Specifies the bias to be applied to the error estimates within accuracy-based adaptivity strategies.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
bias – bias applied to error in accuracy-based time step estimation (default is 1.5).

Return value:

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

Notes:

Any value below 1.0 will imply a reset to the default value.

If both this and one of ERKStepSetAdaptivityMethod() or ERKStepSetAdaptController() will be called, then this routine must be called second.

Deprecated since version 5.7.0: Use the SUNAdaptController infrastructure instead (see §13.1).

int ERKStepSetFixedStepBounds(void *arkode_mem, sunrealtype lb, sunrealtype ub)

Specifies the step growth interval in which the step size will remain unchanged.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
lb – lower bound on window to leave step size fixed (default is 1.0).
ub – upper bound on window to leave step size fixed (default is 1.5).

Return value:

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

Notes:

Any interval not containing 1.0 will imply a reset to the default values.

int ERKStepSetMaxEFailGrowth(void *arkode_mem, sunrealtype etamxf)

Specifies the maximum step size growth factor upon multiple successive accuracy-based error failures in the solver.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
etamxf – time step reduction factor on multiple error fails (default is 0.3).

Return value:

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

Notes:

Any value outside the interval \((0,1]\) will imply a reset to the default value.

int ERKStepSetMaxFirstGrowth(void *arkode_mem, sunrealtype etamx1)

Specifies the maximum allowed growth factor in step size following the very first integration step.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
etamx1 – maximum allowed growth factor after the first time step (default is 10000.0).

Return value:

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

Notes:

Any value \(\le 1.0\) will imply a reset to the default value.

int ERKStepSetMaxGrowth(void *arkode_mem, sunrealtype mx_growth)

Specifies the maximum allowed growth factor in step size between consecutive steps in the integration process.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
mx_growth – maximum allowed growth factor between consecutive time steps (default is 20.0).

Return value:

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

Notes:

Any value \(\le 1.0\) will imply a reset to the default value.

int ERKStepSetMinReduction(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.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
eta_min – minimum allowed reduction factor time step after an error test failure (default is 0.1).

Return value:

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

Notes:

Any value \(\ge 1.0\) or \(\le 0.0\) will imply a reset to the default value.

int ERKStepSetSafetyFactor(void *arkode_mem, sunrealtype safety)

Specifies the safety factor to be applied to the accuracy-based estimated step.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
safety – safety factor applied to accuracy-based time step (default is 0.96).

Return value:

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

Notes:

Any non-positive parameter will imply a reset to the default value.

int ERKStepSetSmallNumEFails(void *arkode_mem, int small_nef)

Specifies the threshold for “multiple” successive error failures before the etamxf parameter from ERKStepSetMaxEFailGrowth() is applied.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
small_nef – bound to determine “multiple” for etamxf (default is 2).

Return value:

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

Notes:

Any non-positive parameter will imply a reset to the default value.

int ERKStepSetStabilityFn(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.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
EStab – name of user-supplied stability function.
estab_data – pointer to user data passed to EStab every time it is called.

Return value:

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

Notes:

This function should return an estimate of the absolute value of the maximum stable time step for the 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 right-hand side function \(f(t,y)\) contains stiff terms.

3.4.3.2.5.4. Rootfinding optional input functions

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

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

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

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

Arguments:

arkode_mem – pointer to the ERKStep 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 ERKStepRootInit()). If rootdir[i] == 0 then crossing in either direction for \(g_i\) should be reported. A value of +1 or -1 indicates that the solver should report only zero-crossings where \(g_i\) is increasing or decreasing, respectively.

Return value:

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

Notes:

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

int ERKStepSetNoInactiveRootWarn(void *arkode_mem)

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

Arguments:

arkode_mem – pointer to the ERKStep memory block.

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ERKStep memory is NULL

Notes:

ERKStep 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), ERKStep will issue a warning which can be disabled with this optional input function.

3.4.3.2.6. Interpolated output function

An optional function ERKStepGetDky() is available to obtain additional values of solution-related quantities. This function should only be called after a successful return from ERKStepEvolve(), 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 ERKStepEvolve(). Internally, this “dense output” or “continuous extension” algorithm is identical to the algorithm used for the maximum order implicit predictors, described in §3.2.11.5.2, except that derivatives of the polynomial model may be evaluated upon request.

int ERKStepGetDky(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 ERKStepSetInterpolantDegree(). The user may request k in the range {0,…, min(degree, kmax)} where kmax depends on the choice of interpolation module. For Hermite interpolants kmax = 5 and for Lagrange interpolants kmax = 3.

Arguments:

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

Return value:

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

Notes:

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

A user may access the values \(t_n\) and \(h_n\) via the functions ERKStepGetCurrentTime() and ERKStepGetLastStep(), respectively.

3.4.3.2.7. Optional output functions

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

General ERKStep output routines are in §3.4.3.2.7.1,
Output routines regarding root-finding results are in §3.4.3.2.7.2,
General usability routines (e.g. to print the current ERKStep parameters, or output the current Butcher table) are in §3.4.3.2.7.3.

Following each table, we elaborate on each function.

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

The counters nsteps and nf_evals provide a rough measure of the overall cost of a given run, and can be compared between runs with different solver options to suggest which set of options is the most efficient.
The ratio nsteps/step_attempts can measure the quality of the time step adaptivity algorithm, since a poor algorithm will result in more failed steps, and hence a lower ratio.

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

3.4.3.2.7.1. Main solver optional output functions

Table 3.7 Main solver optional output functions
Optional output	Function name
Size of ERKStep real and integer workspaces	`ERKStepGetWorkSpace()`
Cumulative number of internal steps	`ERKStepGetNumSteps()`
Actual initial time step size used	`ERKStepGetActualInitStep()`
Step size used for the last successful step	`ERKStepGetLastStep()`
Step size to be attempted on the next step	`ERKStepGetCurrentStep()`
Current internal time reached by the solver	`ERKStepGetCurrentTime()`
Suggested factor for tolerance scaling	`ERKStepGetTolScaleFactor()`
Error weight vector for state variables	`ERKStepGetErrWeights()`
Single accessor to many statistics at once	`ERKStepGetStepStats()`
Print all statistics	`ERKStepPrintAllStats()`
Name of constant associated with a return flag	`ERKStepGetReturnFlagName()`
No. of explicit stability-limited steps	`ERKStepGetNumExpSteps()`
No. of accuracy-limited steps	`ERKStepGetNumAccSteps()`
No. of attempted steps	`ERKStepGetNumStepAttempts()`
No. of calls to f function	`ERKStepGetNumRhsEvals()`
No. of local error test failures that have occurred	`ERKStepGetNumErrTestFails()`
Current ERK Butcher table	`ERKStepGetCurrentButcherTable()`
Estimated local truncation error vector	`ERKStepGetEstLocalErrors()`
Single accessor to many statistics at once	`ERKStepGetTimestepperStats()`
Number of constraint test failures	`ERKStepGetNumConstrFails()`
Retrieve a pointer for user data	`ERKStepGetUserData()`

int ERKStepGetWorkSpace(void *arkode_mem, long int *lenrw, long int *leniw)

Returns the ERKStep real and integer workspace sizes.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
lenrw – the number of sunrealtype values in the ERKStep workspace.
leniw – the number of integer values in the ERKStep workspace.

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ERKStep memory was NULL

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

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

Arguments:

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

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ERKStep memory was NULL

int ERKStepGetActualInitStep(void *arkode_mem, sunrealtype *hinused)

Returns the value of the integration step size used on the first step.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
hinused – actual value of initial step size.

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ERKStep memory was NULL

Notes:

Even if the value of the initial integration step was specified by the user through a call to ERKStepSetInitStep(), this value may have been changed by ERKStep 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.

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

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

Arguments:

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

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ERKStep memory was NULL

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

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

Arguments:

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

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ERKStep memory was NULL

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

Returns the current internal time reached by the solver.

Arguments:

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

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ERKStep memory was NULL

int ERKStepGetTolScaleFactor(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.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
tolsfac – suggested scaling factor for user-supplied tolerances.

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ERKStep memory was NULL

int ERKStepGetErrWeights(void *arkode_mem, N_Vector eweight)

Returns the current error weight vector.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
eweight – solution error weights at the current time.

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ERKStep memory was NULL

Notes:

The user must allocate space for eweight, that will be filled in by this function.

int ERKStepGetStepStats(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.

Arguments:

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

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ERKStep memory was NULL

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

Outputs all of the integrator and other statistics.

Arguments:

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

Return value:

ARK_SUCCESS – if the output was successfully.
CV_MEM_NULL – if the ERKStep memory was NULL.
CV_ILL_INPUT – if an invalid formatting option was provided.

Note

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

New in version 5.2.0.

char *ERKStepGetReturnFlagName(long int flag)

Returns the name of the ERKStep constant corresponding to flag. See Appendix: ARKODE Constants.

Arguments:

flag – a return flag from an ERKStep function.

Return value:

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

int ERKStepGetNumExpSteps(void *arkode_mem, long int *expsteps)

Returns the cumulative number of stability-limited steps taken by the solver (so far).

Arguments:

arkode_mem – pointer to the ERKStep memory block.
expsteps – number of stability-limited steps taken in the solver.

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ERKStep memory was NULL

int ERKStepGetNumAccSteps(void *arkode_mem, long int *accsteps)

Returns the cumulative number of accuracy-limited steps taken by the solver (so far).

Arguments:

arkode_mem – pointer to the ERKStep memory block.
accsteps – number of accuracy-limited steps taken in the solver.

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ERKStep memory was NULL

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

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

Arguments:

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

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ERKStep memory was NULL

int ERKStepGetNumRhsEvals(void *arkode_mem, long int *nf_evals)

Returns the number of calls to the user’s right-hand side function, \(f\) (so far).

Arguments:

arkode_mem – pointer to the ERKStep memory block.
nf_evals – number of calls to the user’s \(f(t,y)\) function.

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ERKStep memory was NULL

int ERKStepGetNumErrTestFails(void *arkode_mem, long int *netfails)

Returns the number of local error test failures that have occurred (so far).

Arguments:

arkode_mem – pointer to the ERKStep memory block.
netfails – number of error test failures.

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ERKStep memory was NULL

int ERKStepGetCurrentButcherTable(void *arkode_mem, ARKodeButcherTable *B)

Returns the Butcher table currently in use by the solver.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
B – pointer to the Butcher table structure.

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ERKStep memory was NULL

Notes:

The ARKodeButcherTable data structure is defined as a pointer to the following C structure:

typedef struct ARKodeButcherTableMem {

  int q;           /* method order of accuracy       */
  int p;           /* embedding order of accuracy    */
  int stages;      /* number of stages               */
  sunrealtype **A;    /* Butcher table coefficients     */
  sunrealtype *c;     /* canopy node coefficients       */
  sunrealtype *b;     /* root node coefficients         */
  sunrealtype *d;     /* embedding coefficients         */

} *ARKodeButcherTable;

For more details see §3.5.

int ERKStepGetEstLocalErrors(void *arkode_mem, N_Vector ele)

Returns the vector of estimated local truncation errors for the current step.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
ele – vector of estimated local truncation errors.

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ERKStep memory was NULL

Notes:

The user must allocate space for ele, that will be filled in by this function.

The values returned in ele are valid only after a successful call to ERKStepEvolve() (i.e., it returned a non-negative value).

The ele vector, together with the eweight vector from ERKStepGetErrWeights(), can be used to determine how the various components of the system contributed to the estimated local error test. Specifically, that error test uses the WRMS norm of a vector whose components are the products of the components of these two vectors. Thus, for example, if there were recent error test failures, the components causing the failures are those with largest values for the products, denoted loosely as eweight[i]*ele[i].

int ERKStepGetTimestepperStats(void *arkode_mem, long int *expsteps, long int *accsteps, long int *step_attempts, long int *nf_evals, long int *netfails)

Returns many of the most useful time-stepper statistics in a single call.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
expsteps – number of stability-limited steps taken in the solver.
accsteps – number of accuracy-limited steps taken in the solver.
step_attempts – number of steps attempted by the solver.
nf_evals – number of calls to the user’s \(f(t,y)\) function.
netfails – number of error test failures.

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ERKStep memory was NULL

int ERKStepGetNumConstrFails(void *arkode_mem, long int *nconstrfails)

Returns the cumulative number of constraint test failures (so far).

Arguments:

arkode_mem – pointer to the ERKStep memory block.
nconstrfails – number of constraint test failures.

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ERKStep memory was NULL

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

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

Arguments:

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

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ARKStep memory was NULL

New in version 5.3.0.

3.4.3.2.7.2. Rootfinding optional output functions

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

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

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

Arguments:

arkode_mem – pointer to the ERKStep 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 ERKStepRootInit()). For \(i = 0 \ldots\) nrtfn-1, rootsfound[i] is nonzero if \(g_i\) has a root, and 0 if not.

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ERKStep memory was NULL

Notes:

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

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

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

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

Arguments:

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

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ERKStep memory was NULL

3.4.3.2.7.3. General usability functions

The following optional routines may be called by a user to inquire about existing solver parameters, to retrieve stored Butcher tables, write the current Butcher table, or even to test a provided Butcher table to determine its analytical order of accuracy. While none of these would typically be called during the course of solving an initial value problem, these may be useful for users wishing to better understand ERKStep and/or specific Runge–Kutta methods.

Table 3.9 General usability functions
Optional routine	Function name
Output all ERKStep solver parameters	`ERKStepWriteParameters()`
Output the current Butcher table	`ERKStepWriteButcher()`

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

Outputs all ERKStep solver parameters to the provided file pointer.

Arguments:

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

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ERKStep memory was NULL

Notes:

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

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

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

Outputs the current Butcher table to the provided file pointer.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
fp – pointer to use for printing the Butcher table.

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ERKStep memory was NULL

Notes:

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

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

3.4.3.2.8. ERKStep re-initialization function

To reinitialize the ERKStep module for the solution of a new problem, where a prior call to ERKStepCreate() has been made, the user must call the function ERKStepReInit(). The new problem must have the same size as the previous one. This routine retains the current settings for all ERKstep module options and performs the same input checking and initializations that are done in ERKStepCreate(), but it performs no memory allocation as is assumes that the existing internal memory is sufficient for the new problem. A call to this re-initialization routine deletes the solution history that was stored internally during the previous integration, and deletes any previously-set tstop value specified via a call to ERKStepSetStopTime(). Following a successful call to ERKStepReInit(), call ERKStepEvolve() again for the solution of the new problem.

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

One important use of the ERKStepReInit() function is in the treating of jump discontinuities in the RHS function. 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 this routine. 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 function 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 function (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 ERKStepReInit(void *arkode_mem, ARKRhsFn f, sunrealtype t0, N_Vector y0)

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

Arguments:

arkode_mem – pointer to the ERKStep memory block.
f – the name of the C function (of type ARKRhsFn()) defining the right-hand side function in \(\dot{y} = f(t,y)\).
t0 – the initial value of \(t\).
y0 – the initial condition vector \(y(t_0)\).

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ERKStep memory was NULL
ARK_MEM_FAIL if a memory allocation failed
ARK_ILL_INPUT if an argument has an illegal value.

Notes:

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

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

3.4.3.2.9. ERKStep reset function

To reset the ERKStep module to a particular state \((t_R,y(t_R))\) for the continued solution of a problem, where a prior call to ERKStepCreate() has been made, the user must call the function ERKStepReset(). Like ERKStepReInit() this routine retains the current settings for all ERKStep module options and performs no memory allocations but, unlike ERKStepReInit(), this routine performs only a subset of the input checking and initializations that are done in ERKStepCreate(). In particular this routine retains all internal counter values and the step size/error history. Like ERKStepReInit(), a call to ERKStepReset() will delete any previously-set tstop value specified via a call to ERKStepSetStopTime(). Following a successful call to ERKStepReset(), call ERKStepEvolve() again to continue solving the problem. By default the next call to ERKStepEvolve() will use the step size computed by ERKStep prior to calling ERKStepReset(). To set a different step size or have ERKStep estimate a new step size use ERKStepSetInitStep().

One important use of the ERKStepReset() 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 ERKStepReset(). 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 ERKStepReset(void *arkode_mem, sunrealtype tR, N_Vector yR)

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

Arguments:

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

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ERKStep memory was NULL
ARK_MEM_FAIL if a memory allocation failed
ARK_ILL_INPUT if an argument has an illegal value.

Notes:

By default the next call to ERKStepEvolve() will use the step size computed by ERKStep prior to calling ERKStepReset(). To set a different step size or have ERKStep estimate a new step size use ERKStepSetInitStep().

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

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

3.4.3.2.10. ERKStep 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 ERKStep integrator may be “resized” between integration steps, through calls to the ERKStepResize() function. This function modifies ERKStep’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 ERKStepResize() remain valid after the call. If instead the dynamics should be recomputed from scratch, the ERKStep memory structure should be deleted with a call to ERKStepFree(), and recreated with a call to ERKStepCreate().

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 ERKStep 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 ERKStepResize(void *arkode_mem, N_Vector yR, sunrealtype hscale, sunrealtype tR, ARKVecResizeFn resize, void *resize_data)

Re-sizes ERKStep with a different state vector but with comparable dynamical time scale.

Arguments:

arkode_mem – pointer to the ERKStep memory block.
yR – the newly-sized solution 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 ERKStep vectors.

Return value:

ARK_SUCCESS if successful
ARK_MEM_NULL if the ERKStep memory was NULL
ARK_NO_MALLOC if arkode_mem was not allocated.
ARK_ILL_INPUT if an argument has an illegal value.

Notes:

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

If inequality constraint checking is enabled a call to ERKStepResize() will disable constraint checking. A call to ERKStepSetConstraints() is required to re-enable constraint checking.

3.4.3.2.10.1. Resizing the absolute tolerance array

If using array-valued absolute tolerances, the absolute tolerance vector will be invalid after the call to ERKStepResize(), so the new absolute tolerance vector should be re-set following each call to ERKStepResize() through a new call to ERKStepSVtolerances().

If scalar-valued tolerances or a tolerance function was specified through either ERKStepSStolerances() or ERKStepWFtolerances(), then these will remain valid and no further action is necessary.

Note

For an example showing usage of the similar ARKStepResize() routine, see the supplied serial C example problem, ark_heat1D_adapt.c.