2.4.7.1. ARKStep User-callable functions

This section describes the ARKStep-specific functions that may be called by the user to setup and then solve an IVP using the ARKStep time-stepping module. The large majority of these routines merely wrap underlying ARKODE functions, and are now deprecated – each of these are clearly marked. However, some of these user-callable functions are specific to ARKStep, as explained below.

As discussed in the main ARKODE user-callable function introduction, each of ARKODE’s time-stepping modules clarifies the categories of user-callable functions that it supports. ARKStep supports all categories:

  • temporal adaptivity

  • implicit nonlinear and/or linear solvers

  • non-identity mass matrices

  • relaxation Runge–Kutta methods

ARKStep also has forcing function support when converted to a SUNStepper or MRIStepInnerStepper. See ARKodeCreateSUNStepper() and ARKStepCreateMRIStepInnerStepper() for additional details.

2.4.7.1.1. ARKStep initialization and deallocation functions

void *ARKStepCreate(ARKRhsFn fe, ARKRhsFn fi, sunrealtype t0, N_Vector y0, SUNContext sunctx)

This function creates an internal memory block for a problem to be solved using the ARKStep time-stepping module in ARKODE.

Arguments:

  • fe – the name of the C function (of type ARKRhsFn()) defining the explicit portion of the right-hand side function in \(M(t)\, y'(t) = f^E(t,y) + f^I(t,y)\).

  • fi – the name of the C function (of type ARKRhsFn()) defining the implicit portion of the right-hand side function in \(M(t)\, y'(t) = f^E(t,y) + f^I(t,y)\).

  • t0 – the initial value of \(t\).

  • y0 – the initial condition vector \(y(t_0)\).

  • sunctx – the SUNContext object (see §1.3)

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

void ARKStepFree(void **arkode_mem)

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

Return value: None

Deprecated since version 6.1.0: Use ARKodeFree() instead.

2.4.7.1.2. ARKStep tolerance specification functions

int ARKStepSStolerances(void *arkode_mem, sunrealtype reltol, sunrealtype abstol)

This function specifies scalar relative and absolute tolerances.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • reltol – scalar relative tolerance.

  • abstol – scalar absolute tolerance.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

  • ARK_NO_MALLOC if the ARKStep memory was not allocated by the time-stepping module

  • ARK_ILL_INPUT if an argument had an illegal value (e.g. a negative tolerance).

Deprecated since version 6.1.0: Use ARKodeSStolerances() instead.

int ARKStepSVtolerances(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 ARKStep memory block.

  • reltol – scalar relative tolerance.

  • abstol – vector containing the absolute tolerances for each solution component.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

  • ARK_NO_MALLOC if the ARKStep memory was not allocated by the time-stepping module

  • ARK_ILL_INPUT if an argument had an illegal value (e.g. a negative tolerance).

Deprecated since version 6.1.0: Use ARKodeSVtolerances() instead.

int ARKStepWFtolerances(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 ARKStep memory block.

  • efun – the name of the function (of type ARKEwtFn()) that implements the error weight vector computation.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

  • ARK_NO_MALLOC if the ARKStep memory was not allocated by the time-stepping module

Deprecated since version 6.1.0: Use ARKodeWFtolerances() instead.

int ARKStepResStolerance(void *arkode_mem, sunrealtype rabstol)

This function specifies a scalar absolute residual tolerance.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • rabstol – scalar absolute residual tolerance.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

  • ARK_NO_MALLOC if the ARKStep memory was not allocated by the time-stepping module

  • ARK_ILL_INPUT if an argument had an illegal value (e.g. a negative tolerance).

Deprecated since version 6.1.0: Use ARKodeResStolerance() instead.

int ARKStepResVtolerance(void *arkode_mem, N_Vector rabstol)

This function specifies a vector of absolute residual tolerances.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • rabstol – vector containing the absolute residual tolerances for each solution component.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

  • ARK_NO_MALLOC if the ARKStep memory was not allocated by the time-stepping module

  • ARK_ILL_INPUT if an argument had an illegal value (e.g. a negative tolerance).

Deprecated since version 6.1.0: Use ARKodeResVtolerance() instead.

int ARKStepResFtolerance(void *arkode_mem, ARKRwtFn rfun)

This function specifies a user-supplied function rfun to compute the residual weight vector rwt.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • rfun – the name of the function (of type ARKRwtFn()) that implements the residual weight vector computation.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

  • ARK_NO_MALLOC if the ARKStep memory was not allocated by the time-stepping module

Deprecated since version 6.1.0: Use ARKodeResFtolerance() instead.

2.4.7.1.3. Linear solver interface functions

int ARKStepSetLinearSolver(void *arkode_mem, SUNLinearSolver LS, SUNMatrix J)

This function specifies the SUNLinearSolver object that ARKStep should use, as well as a template Jacobian SUNMatrix object (if applicable).

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • LS – the SUNLinearSolver object to use.

  • J – the template Jacobian SUNMatrix object to use (or NULL if not applicable).

Return value:

  • ARKLS_SUCCESS if successful

  • ARKLS_MEM_NULL if the ARKStep memory was NULL

  • ARKLS_MEM_FAIL if there was a memory allocation failure

  • ARKLS_ILL_INPUT if ARKLS is incompatible with the provided LS or J input objects, or the current N_Vector module.

Notes:

If LS is a 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 ARKStep.

Deprecated since version 6.1.0: Use ARKodeSetLinearSolver() instead.

2.4.7.1.4. Mass matrix solver specification functions

int ARKStepSetMassLinearSolver(void *arkode_mem, SUNLinearSolver LS, SUNMatrix M, sunbooleantype time_dep)

This function specifies the SUNLinearSolver object that ARKStep should use for mass matrix systems, as well as a template SUNMatrix object.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • LS – the SUNLinearSolver object to use.

  • M – the template mass SUNMatrix object to use.

  • time_dep – flag denoting whether the mass matrix depends on the independent variable (\(M = M(t)\)) or not (\(M \ne M(t)\)). SUNTRUE indicates time-dependence of the mass matrix.

Return value:

  • ARKLS_SUCCESS if successful

  • ARKLS_MEM_NULL if the ARKStep memory was NULL

  • ARKLS_MEM_FAIL if there was a memory allocation failure

  • ARKLS_ILL_INPUT if ARKLS is incompatible with the provided LS or M input objects, or the current N_Vector module.

Notes:

If LS is a 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 ARKStepReInit() or ARKStepResize() are called), with the results reused throughout the entire ARKStep simulation.

Unlike the system Jacobian, the system mass matrix is not approximated using finite-differences of any functions provided to ARKStep. Hence, use of the a matrix-based LS requires the user to provide a mass-matrix constructor routine (see ARKLsMassFn and ARKStepSetMassFn()).

Similarly, the system mass matrix-vector-product is not approximated using finite-differences of any functions provided to ARKStep. Hence, use of a matrix-free LS requires the user to provide a mass-matrix-times-vector product routine (see ARKLsMassTimesVecFn and ARKStepSetMassTimes()).

Deprecated since version 6.1.0: Use ARKodeSetMassLinearSolver() instead.

2.4.7.1.5. Nonlinear solver interface functions

int ARKStepSetNonlinearSolver(void *arkode_mem, SUNNonlinearSolver NLS)

This function specifies the SUNNonlinearSolver object that ARKStep should use for implicit stage solves.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • NLS – the SUNNonlinearSolver object to use.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

  • ARK_MEM_FAIL if there was a memory allocation failure

  • ARK_ILL_INPUT if ARKStep is incompatible with the provided NLS input object.

Notes:

ARKStep will use the Newton SUNNonlinearSolver module by default; a call to this routine replaces that module with the supplied NLS object.

Deprecated since version 6.1.0: Use ARKodeSetNonlinearSolver() instead.

2.4.7.1.6. Rootfinding initialization function

int ARKStepRootInit(void *arkode_mem, int nrtfn, ARKRootFn g)

Initializes a rootfinding problem to be solved during the integration of the ODE system. It must be called after ARKStepCreate(), and before ARKStepEvolve().

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • nrtfn – number of functions \(g_i\), an integer \(\ge\) 0.

  • g – name of 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 ARKStep memory was NULL

  • ARK_MEM_FAIL if there was a memory allocation failure

  • ARK_ILL_INPUT if nrtfn is greater than zero but g = NULL.

Notes:

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

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

Deprecated since version 6.1.0: Use ARKodeRootInit() instead.

2.4.7.1.7. ARKStep solver function

int ARKStepEvolve(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 ARKStep memory block.

  • tout – the next time at which a computed solution is desired.

  • yout – the computed solution vector.

  • tret – the time corresponding to yout (output).

  • itask – a flag indicating the job of the solver for the next user step.

    The ARK_NORMAL option causes the solver to take internal steps until it has just overtaken a 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 (as described in §2.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 ARKStepEvolve() succeeded, and found one or more roots. If the number of root functions, nrtfn, is greater than 1, call ARKStepGetRootInfo() to see which \(g_i\) were found to have a root at (*tret).

  • ARK_TSTOP_RETURN if ARKStepEvolve() succeeded and returned at tstop.

  • ARK_MEM_NULL if the arkode_mem argument was NULL.

  • ARK_NO_MALLOC if arkode_mem was not allocated.

  • ARK_ILL_INPUT if one of the inputs to ARKStepEvolve() is illegal, or some other input to the solver was either illegal or missing. Details will be provided in the error message. Typical causes of this failure:

    1. A component of the error weight vector became zero during internal time-stepping.

    2. The linear solver initialization function (called by the user after calling ARKStepCreate()) failed to set the linear solver-specific lsolve field in arkode_mem.

    3. A root of one of the root functions was found both at a point \(t\) and also very near \(t\).

    4. The initial condition violates the inequality constraints.

  • ARK_TOO_MUCH_WORK if the solver took mxstep internal steps but could not reach tout. The default value for mxstep is MXSTEP_DEFAULT = 500.

  • ARK_TOO_MUCH_ACC if the solver could not satisfy the accuracy demanded by the user for some internal step.

  • ARK_ERR_FAILURE if error test failures occurred either too many times (ark_maxnef) during one internal time step or occurred with \(|h| = h_{min}\).

  • ARK_CONV_FAILURE if either convergence test failures occurred too many times (ark_maxncf) during one internal time step or occurred with \(|h| = h_{min}\).

  • ARK_LINIT_FAIL if the linear solver’s initialization function failed.

  • ARK_LSETUP_FAIL if the linear solver’s setup routine failed in an unrecoverable manner.

  • ARK_LSOLVE_FAIL if the linear solver’s solve routine failed in an unrecoverable manner.

  • ARK_MASSINIT_FAIL if the mass matrix solver’s initialization function failed.

  • ARK_MASSSETUP_FAIL if the mass matrix solver’s setup routine failed.

  • ARK_MASSSOLVE_FAIL if the mass matrix solver’s solve routine failed.

  • ARK_VECTOROP_ERR a vector operation error occurred.

Notes:

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

In ARK_ONE_STEP mode, tout is used only on the first call, and only to get the direction and a rough scale of the independent variable.

All failure return values are negative and so testing the return argument for negative values will trap all ARKStepEvolve() failures.

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

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

Deprecated since version 6.1.0: Use ARKodeEvolve() instead.

2.4.7.1.8. Optional input functions

2.4.7.1.8.1. Optional inputs for ARKStep

int ARKStepSetDefaults(void *arkode_mem)

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

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 ARKStepRootInit()).

Deprecated since version 6.1.0: Use ARKodeSetDefaults() instead.

int ARKStepSetInterpolantType(void *arkode_mem, int itype)

Deprecated since version 6.1.0: This function is now a wrapper to ARKodeSetInterpolantType(), see the documentation for that function instead.

int ARKStepSetInterpolantDegree(void *arkode_mem, int degree)

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • degree – requested polynomial degree.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory or interpolation module are NULL

  • ARK_INTERP_FAIL if this is called after ARKStepEvolve()

  • ARK_ILL_INPUT if an argument had an illegal value or the interpolation module has already been initialized

Notes:

Allowed values are between 0 and 5.

This routine should be called after ARKStepCreate() and before ARKStepEvolve(). After the first call to ARKStepEvolve() the interpolation degree may not be changed without first calling ARKStepReInit().

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

Deprecated since version 6.1.0: Use ARKodeSetInterpolantDegree() instead.

int ARKStepSetDenseOrder(void *arkode_mem, int dord)

Deprecated since version 5.2.0: Use ARKodeSetInterpolantDegree() instead.

int ARKStepSetDiagnostics(void *arkode_mem, FILE *diagfp)

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • diagfp – pointer to the diagnostics output file.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had 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 ARKStepSetFixedStep(void *arkode_mem, sunrealtype hfixed)

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • hfixed – value of the fixed step size to use.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

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

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

When using ARKStepSetFixedStep(), any values provided to the functions ARKStepSetInitStep(), ARKStepSetAdaptivityFn(), ARKStepSetMaxErrTestFails(), ARKStepSetAdaptivityMethod(), ARKStepSetCFLFraction(), ARKStepSetErrorBias(), ARKStepSetFixedStepBounds(), ARKStepSetMaxCFailGrowth(), ARKStepSetMaxEFailGrowth(), ARKStepSetMaxFirstGrowth(), ARKStepSetMaxGrowth(), ARKStepSetMinReduction(), ARKStepSetSafetyFactor(), ARKStepSetSmallNumEFails(), ARKStepSetStabilityFn(), and ARKStepSetAdaptController() will be ignored, since temporal adaptivity is disabled.

If both ARKStepSetFixedStep() and ARKStepSetStopTime() 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 ARKStepSetFixedStep() must be made prior to calling ARKStepEvolve() to resume integration.

It is not recommended that ARKStepSetFixedStep() be used in concert with ARKStepSetMaxStep() or ARKStepSetMinStep(), 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.

Deprecated since version 6.1.0: Use ARKodeSetFixedStep() instead.

int ARKStepSetInitStep(void *arkode_mem, sunrealtype hin)

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • hin – value of the initial step to be attempted \((\ne 0)\).

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

Pass 0.0 to use the default value.

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

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

Deprecated since version 6.1.0: Use ARKodeSetInitStep() instead.

int ARKStepSetMaxHnilWarns(void *arkode_mem, int mxhnil)

Specifies the maximum number of messages issued by the solver to warn that \(t+h=t\) on the next internal step, before ARKStep will instead return with an error.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • mxhnil – maximum allowed number of warning messages \((>0)\).

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had 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.

Deprecated since version 6.1.0: Use ARKodeSetMaxHnilWarns() instead.

int ARKStepSetMaxNumSteps(void *arkode_mem, long int mxsteps)

Specifies the maximum number of steps to be taken by the solver in its attempt to reach the next output time, before ARKStep will return with an error.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • mxsteps – maximum allowed number of internal steps.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

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

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

Deprecated since version 6.1.0: Use ARKodeSetMaxNumSteps() instead.

int ARKStepSetMaxStep(void *arkode_mem, sunrealtype hmax)

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • hmax – maximum absolute value of the time step size \((\ge 0)\).

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

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

Deprecated since version 6.1.0: Use ARKodeSetMaxStep() instead.

int ARKStepSetMinStep(void *arkode_mem, sunrealtype hmin)

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • hmin – minimum absolute value of the time step size \((\ge 0)\).

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

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

Deprecated since version 6.1.0: Use ARKodeSetMinStep() instead.

int ARKStepSetStopTime(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 ARKStep memory block.

  • tstop – stopping time for the integrator.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had 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 re-enabled only though a new call to ARKStepSetStopTime()).

A stop time not reached before a call to ARKStepReInit() or ARKStepReset() will remain active but can be disabled by calling ARKStepClearStopTime().

Deprecated since version 6.1.0: Use ARKodeSetStopTime() instead.

int ARKStepSetInterpolateStopTime(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 ARKStep 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

Added in version 5.6.0.

Deprecated since version 6.1.0: Use ARKodeSetInterpolateStopTime() instead.

int ARKStepClearStopTime(void *arkode_mem)

Disables the stop time set with ARKStepSetStopTime().

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

Notes:

The stop time can be re-enabled though a new call to ARKStepSetStopTime().

Added in version 5.5.1.

Deprecated since version 6.1.0: Use ARKodeClearStopTime() instead.

int ARKStepSetUserData(void *arkode_mem, void *user_data)

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • user_data – pointer to the user data.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had 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.

If user_data is needed in user preconditioner functions, the call to this function must be made before any calls to ARKStepSetLinearSolver() and/or ARKStepSetMassLinearSolver().

Deprecated since version 6.1.0: Use ARKodeSetUserData() instead.

int ARKStepSetMaxErrTestFails(void *arkode_mem, int maxnef)

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • maxnef – maximum allowed number of error test failures \((>0)\).

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

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

Deprecated since version 6.1.0: Use ARKodeSetMaxErrTestFails() instead.

int ARKStepSetOptimalParams(void *arkode_mem)

Sets all adaptivity and solver parameters to our “best guess” values for a given integration method type (ERK, DIRK, ARK) and a given method order.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

Should only be called after the method order and integration method have been set. The “optimal” values resulted from repeated testing of ARKStep’s solvers on a variety of training problems. However, all problems are different, so these values may not be optimal for all users.

Deprecated since version 6.1.0: Adjust solver parameters individually instead. For reference, this routine sets the following non-default parameters:

int ARKStepSetConstraints(void *arkode_mem, N_Vector constraints)

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • constraints – vector of constraint flags. Each component specifies the type of solution constraint:

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

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if the constraints vector contains illegal values

Notes:

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

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

Deprecated since version 6.1.0: Use ARKodeSetConstraints() instead.

int ARKStepSetMaxNumConstrFails(void *arkode_mem, int maxfails)

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • maxfails – maximum allowed number of constrain failures.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

Notes:

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

Deprecated since version 6.1.0: Use ARKodeSetMaxNumConstrFails() instead.

2.4.7.1.8.2. Optional inputs for IVP method selection

Optional input

Function name

Default

Set integrator method order

ARKStepSetOrder()

4

Specify implicit/explicit problem

ARKStepSetImEx()

SUNTRUE

Specify explicit problem

ARKStepSetExplicit()

SUNFALSE

Specify implicit problem

ARKStepSetImplicit()

SUNFALSE

Set additive RK tables

ARKStepSetTables()

internal

Set additive RK tables via their numbers

ARKStepSetTableNum()

internal

Set additive RK tables via their names

ARKStepSetTableName()

internal
int ARKStepSetOrder(void *arkode_mem, int ord)

Specifies the order of accuracy for the ARK/DIRK/ERK integration method.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • ord – requested order of accuracy.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

For explicit methods, the allowed values are \(2 \le\) ord \(\le 8\). For implicit methods, the allowed values are \(2\le\) ord \(\le 5\), and for ImEx methods the allowed values are \(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 ARKStep memory block, it cannot be changed after the first call to ARKStepEvolve(), unless ARKStepReInit() is called.

Deprecated since version 6.1.0: Use ARKodeSetOrder() instead.

int ARKStepSetImEx(void *arkode_mem)

Specifies that both the implicit and explicit portions of problem are enabled, and to use an additive Runge–Kutta method.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

This is automatically deduced when neither of the function pointers fe or fi passed to ARKStepCreate() are NULL, but may be set directly by the user if desired.

int ARKStepSetExplicit(void *arkode_mem)

Specifies that the implicit portion of problem is disabled, and to use an explicit RK method.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

This is automatically deduced when the function pointer fi passed to ARKStepCreate() is NULL, but may be set directly by the user if desired.

If the problem is posed in explicit form, i.e. \(\dot{y} = f(t,y)\), then we recommend that the ERKStep time-stepper module be used instead.

int ARKStepSetImplicit(void *arkode_mem)

Specifies that the explicit portion of problem is disabled, and to use a diagonally implicit RK method.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

This is automatically deduced when the function pointer fe passed to ARKStepCreate() is NULL, but may be set directly by the user if desired.

int ARKStepSetTables(void *arkode_mem, int q, int p, ARKodeButcherTable Bi, ARKodeButcherTable Be)

Specifies a customized Butcher table (or pair) for the ERK, DIRK, or ARK method.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • q – global order of accuracy for the ARK method.

  • p – global order of accuracy for the embedded ARK method.

  • Bi – the Butcher table for the implicit RK method.

  • Be – the Butcher table for the explicit RK method.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

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

To set an explicit table, Bi must be NULL. This automatically calls ARKStepSetExplicit(). However, if the problem is posed in explicit form, i.e. \(\dot{y} = f(t,y)\), then we recommend that the ERKStep time-stepper module be used instead of ARKStep.

To set an implicit table, Be must be NULL. This automatically calls ARKStepSetImplicit().

If both Bi and Be are provided, this routine automatically calls ARKStepSetImEx().

When only one table is provided (i.e., Bi or Be is NULL) then the input values of q and p are ignored and the global order of the method and embedding (if applicable) are obtained from the Butcher table structures. If both Bi and Be are non-NULL (e.g, an ImEx method is provided) then the input values of q and p are used as the order of the ARK method may be less than the orders of the individual tables. No error checking is performed to ensure that either p or q correctly describe the coefficients that were input.

Error checking is subsequently performed at ARKStep initialization to ensure that Bi and Be (if non-NULL) specify DIRK and ERK methods, respectively. Specifically, the A member of Bi must be lower triangular with at least one nonzero value on the diagonal, and the A member of Be must be strictly lower triangular. When both Bi and Be are non-NULL, they must agree on the number of internal stages, i.e., the stages members of both structures must match.

If the inputs Bi or Be do not contain an embedding (when the corresponding explicit or implicit table is non-NULL), the user must call ARKStepSetFixedStep() to enable fixed-step mode and set the desired time step size.

Warning:

This should not be used with ARKodeSetOrder().

int ARKStepSetTableNum(void *arkode_mem, ARKODE_DIRKTableID itable, ARKODE_ERKTableID etable)

Indicates to use specific built-in Butcher tables for the ERK, DIRK or ARK method.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • itable – index of the DIRK Butcher table.

  • etable – index of the ERK Butcher table.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

The allowable values for both the itable and etable arguments corresponding to built-in tables may be found in §2.8.

To choose an explicit table, set itable to a negative value. This automatically calls ARKStepSetExplicit(). However, if the problem is posed in explicit form, i.e. \(\dot{y} = f(t,y)\), then we recommend that the ERKStep time-stepper module be used instead of ARKStep.

To select an implicit table, set etable to a negative value. This automatically calls ARKStepSetImplicit().

If both itable and etable are non-negative, then these should match an existing implicit/explicit pair, listed in §2.8.3. This automatically calls ARKStepSetImEx().

In all cases, error-checking is performed to ensure that the tables exist.

Warning:

This should not be used with ARKodeSetOrder().

int ARKStepSetTableName(void *arkode_mem, const char *itable, const char *etable)

Indicates to use specific built-in Butcher tables for the ERK, DIRK or ARK method.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • itable – name of the DIRK Butcher table.

  • etable – name of the ERK Butcher table.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

The allowable values for both the itable and etable arguments corresponding to built-in tables may be found in §2.8. This function is case sensitive.

To choose an explicit table, set itable to "ARKODE_DIRK_NONE". This automatically calls ARKStepSetExplicit(). However, if the problem is posed in explicit form, i.e. \(\dot{y} = f(t,y)\), then we recommend that the ERKStep time-stepper module be used instead of ARKStep.

To select an implicit table, set etable to "ARKODE_ERK_NONE". This automatically calls ARKStepSetImplicit().

If both itable and etable are not none, then these should match an existing implicit/explicit pair, listed in §2.8.3. This automatically calls ARKStepSetImEx().

In all cases, error-checking is performed to ensure that the tables exist.

Warning:

This should not be used with ARKodeSetOrder().

2.4.7.1.8.3. Optional inputs for time step adaptivity

int ARKStepSetAdaptController(void *arkode_mem, SUNAdaptController C)

Sets a user-supplied time-step controller object.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • C – user-supplied time adaptivity controller. If NULL then the I controller will be created (see §12.2).

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_MEM_FAIL if C was NULL and the I controller could not be allocated.

Added in version 5.7.0.

Deprecated since version 6.1.0: Use ARKodeSetAdaptController() instead.

Changed in version 6.3.0: The default controller was changed from PID to I.

int ARKStepSetAdaptivityFn(void *arkode_mem, ARKAdaptFn hfun, void *h_data)

Sets a user-supplied time-step adaptivity function.

Arguments:

  • arkode_mem – pointer to the ARKStep 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 ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

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

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

int ARKStepSetAdaptivityMethod(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 ARKStep 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 ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

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

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 §12.1).

int ARKStepSetAdaptivityAdjustment(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 ARKStep memory block.

  • adjust – adjustment factor (default is 0).

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

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

Added in version 5.7.0.

Deprecated since version 6.1.0: Use ARKodeSetAdaptivityAdjustment() instead.

Changed in version 6.3.0: The default value was changed from -1 to 0

int ARKStepSetCFLFraction(void *arkode_mem, sunrealtype cfl_frac)

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • cfl_frac – maximum allowed fraction of explicitly stable step (default is 0.5).

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

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

Deprecated since version 6.1.0: Use ARKodeSetCFLFraction() instead.

int ARKStepSetErrorBias(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 ARKStep memory block.

  • bias – bias applied to error in accuracy-based time step estimation (default is 1.0).

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

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

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

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

Changed in version 6.3.0: The default value was changed from 1.5 to 1.0

int ARKStepSetFixedStepBounds(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 ARKStep memory block.

  • lb – lower bound on window to leave step size fixed (default is 1.0).

  • ub – upper bound on window to leave step size fixed (default is 1.0).

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

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

Deprecated since version 6.1.0: Use ARKodeSetFixedStepBounds() instead.

Changed in version 6.3.0: The default upper bound was changed from 1.5 to 1.0

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • etacf – time step reduction factor on a nonlinear solver convergence failure (default is 0.25).

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

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

Deprecated since version 6.1.0: Use ARKodeSetMaxCFailGrowth() instead.

int ARKStepSetMaxEFailGrowth(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 ARKStep memory block.

  • etamxf – time step reduction factor on multiple error fails (default is 0.3).

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

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

Deprecated since version 6.1.0: Use ARKodeSetMaxEFailGrowth() instead.

int ARKStepSetMaxFirstGrowth(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 ARKStep memory block.

  • etamx1 – maximum allowed growth factor after the first time step (default is 10000.0).

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

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

Deprecated since version 6.1.0: Use ARKodeSetMaxFirstGrowth() instead.

int ARKStepSetMaxGrowth(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 ARKStep memory block.

  • mx_growth – maximum allowed growth factor between consecutive time steps (default is 20.0).

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

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

Deprecated since version 6.1.0: Use ARKodeSetMaxGrowth() instead.

int ARKStepSetMinReduction(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 ARKStep memory block.

  • eta_min – minimum allowed reduction factor in time step after an error test failure (default is 0.1).

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

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

Deprecated since version 6.1.0: Use ARKodeSetMinReduction() instead.

int ARKStepSetSafetyFactor(void *arkode_mem, sunrealtype safety)

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • safety – safety factor applied to accuracy-based time step (default is 0.9).

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

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

Deprecated since version 6.1.0: Use ARKodeSetSafetyFactor() instead.

Changed in version 6.3.0: The default default was changed from 0.96 to 0.9. The maximum value is now exactly 1.0 rather than strictly less than 1.0.

int ARKStepSetSmallNumEFails(void *arkode_mem, int small_nef)

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • small_nef – bound to determine ‘multiple’ for etamxf (default is 2).

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

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

Deprecated since version 6.1.0: Use ARKodeSetSmallNumEFails() instead.

int ARKStepSetStabilityFn(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 ARKStep 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 ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

This function should return an estimate of the absolute value of the maximum stable time step for the explicit portion of the ODE system. It is not required, since 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.

Deprecated since version 6.1.0: Use ARKodeSetStabilityFn() instead.

2.4.7.1.8.4. Optional inputs for implicit stage solves

int ARKStepSetLinear(void *arkode_mem, int timedepend)

Specifies that the implicit portion of the problem is linear.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • timedepend – flag denoting whether the Jacobian of \(f^I(t,y)\) is time-dependent (1) or not (0).

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

Tightens the linear solver tolerances and takes only a single Newton iteration. Calls ARKStepSetDeltaGammaMax() to enforce Jacobian recomputation when the step size ratio changes by more than 100 times the unit roundoff (since nonlinear convergence is not tested). Only applicable when used in combination with the modified or inexact Newton iteration (not the 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.

Deprecated since version 6.1.0: Use ARKodeSetLinear() instead.

int ARKStepSetNonlinear(void *arkode_mem)

Specifies that the implicit portion of the problem is nonlinear.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

This is the default behavior of ARKStep, so the function is primarily useful to undo a previous call to ARKStepSetLinear(). Calls ARKStepSetDeltaGammaMax() to reset the step size ratio threshold to the default value.

Deprecated since version 6.1.0: Use ARKodeSetNonlinear() instead.

int ARKStepSetPredictorMethod(void *arkode_mem, int method)

Specifies the method from §2.2.15.5 to use for predicting implicit solutions.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • method – method choice (0 \(\le\) method \(\le\) 4):

    • 0 is the trivial predictor,

    • 1 is the maximum order (dense output) predictor,

    • 2 is the variable order predictor, that decreases the polynomial degree for more distant RK stages,

    • 3 is the cutoff order predictor, that uses the maximum order for early RK stages, and a first-order predictor for distant RK stages,

    • 4 is the bootstrap predictor, that uses a second-order predictor based on only information within the current step. deprecated

    • 5 is the minimum correction predictor, that uses all preceding stage information within the current step for prediction. deprecated

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

The default value is 0. If method is set to an undefined value, this default predictor will be used.

Options 4 and 5 are currently not supported when solving a problem involving a non-identity mass matrix. In that case, selection of method as 4 or 5 will instead default to the trivial predictor (method 0). Both of these options have been deprecated, and will be removed from a future release.

Deprecated since version 6.1.0: Use ARKodeSetPredictorMethod() instead.

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • PredictStage – name of user-supplied predictor function. If NULL, then any previously-provided stage prediction function will be disabled.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

Notes:

See §2.4.4.6 for more information on this user-supplied routine.

Deprecated since version 6.1.0: Use ARKodeSetStagePredictFn() instead.

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • nls_fi – the alternative C function for computing the right-hand side function \(f^I(t,y)\) in the ODE.

Return value:

  • ARK_SUCCESS if successful.

  • ARK_MEM_NULL if the ARKStep memory was NULL.

Notes:

The default is to use the implicit right-hand side function provided to ARKStepCreate() 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 ARKStepSetNonlinearSolver().

Deprecated since version 6.1.0: Use ARKodeSetNlsRhsFn() instead.

int ARKStepSetMaxNonlinIters(void *arkode_mem, int maxcor)

Specifies the maximum number of nonlinear solver iterations permitted per implicit stage solve within each time step.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • maxcor – maximum allowed solver iterations per stage \((>0)\).

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value or if the SUNNONLINSOL module is NULL

  • ARK_NLS_OP_ERR if the SUNNONLINSOL object returned a failure flag

Notes:

The default value is 3; set maxcor \(\le 0\) to specify this default.

Deprecated since version 6.1.0: Use ARKodeSetMaxNonlinIters() instead.

int ARKStepSetNonlinConvCoef(void *arkode_mem, sunrealtype nlscoef)

Specifies the safety factor \(\epsilon\) used within the nonlinear solver convergence test (2.58).

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • nlscoef – coefficient in nonlinear solver convergence test \((>0.0)\).

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

The default value is 0.1; set nlscoef \(\le 0\) to specify this default.

Deprecated since version 6.1.0: Use ARKodeSetNonlinConvCoef() instead.

int ARKStepSetNonlinCRDown(void *arkode_mem, sunrealtype crdown)

Specifies the constant \(c_r\) used in estimating the nonlinear solver convergence rate (2.57).

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • crdown – nonlinear convergence rate estimation constant (default is 0.3).

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

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

Deprecated since version 6.1.0: Use ARKodeSetNonlinCRDown() instead.

int ARKStepSetNonlinRDiv(void *arkode_mem, sunrealtype rdiv)

Specifies the nonlinear correction threshold \(r_{div}\) from (2.59), beyond which the iteration will be declared divergent.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • rdiv – tolerance on nonlinear correction size ratio to declare divergence (default is 2.3).

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

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

Deprecated since version 6.1.0: Use ARKodeSetNonlinRDiv() instead.

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • maxncf – maximum allowed nonlinear solver convergence failures per step \((>0)\).

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

The default value is 10; set maxncf \(\le 0\) to specify this default.

Upon each convergence failure, ARKStep will first call the Jacobian setup routine and try again (if a Newton method is used). If a convergence failure still occurs, the time step size is reduced by the factor etacf (set within ARKStepSetMaxCFailGrowth()).

Deprecated since version 6.1.0: Use ARKodeSetMaxConvFails() instead.

int ARKStepSetDeduceImplicitRhs(void *arkode_mem, sunbooleantype deduce)

Specifies if implicit stage derivatives are deduced without evaluating \(f^I\). See §2.2.15.1 for more details.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • deduce – If SUNFALSE (default), the stage derivative is obtained by evaluating \(f^I\) with the stage solution returned from the nonlinear solver. If SUNTRUE, the stage derivative is deduced without an additional evaluation of \(f^I\).

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

Added in version 5.2.0.

Deprecated since version 6.1.0: Use ARKodeSetDeduceImplicitRhs() instead.

2.4.7.1.8.5. Linear solver interface optional input functions

2.4.7.1.8.5.1. Optional inputs for the ARKLS linear solver interface

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • dgmax – tolerance on step size ratio change before calling linear solver setup routine (default is 0.2).

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

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

Deprecated since version 6.1.0: Use ARKodeSetDeltaGammaMax() instead.

int ARKStepSetLSetupFrequency(void *arkode_mem, int msbp)

Specifies the frequency of calls to the linear solver setup routine, \(msbp\) from §2.2.15.2.3.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • msbp – the linear solver setup frequency.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

Notes:

Positive values of msbp specify the linear solver setup frequency. For example, an input of 1 means the setup function will be called every time step while an input of 2 means it will be called called every other time step. If msbp is 0, the default value of 20 will be used. A negative value forces a linear solver step at each implicit stage.

Deprecated since version 6.1.0: Use ARKodeSetLSetupFrequency() instead.

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • msbj – the Jacobian re-computation or preconditioner update frequency.

Return value:

  • ARKLS_SUCCESS if successful.

  • ARKLS_MEM_NULL if the ARKStep memory was NULL.

  • ARKLS_LMEM_NULL if the linear solver memory was NULL.

Notes:

If nstlj is the step number at which the Jacobian information was lasted updated and nst 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 ARKStepSetLinearSolver().

Deprecated since version 6.1.0: Use ARKodeSetJacEvalFrequency() instead.

2.4.7.1.8.5.2. Optional inputs for matrix-based SUNLinearSolver modules

int ARKStepSetJacFn(void *arkode_mem, ARKLsJacFn jac)

Specifies the Jacobian approximation routine to be used for the matrix-based solver with the ARKLS interface.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • jac – name of user-supplied Jacobian approximation function.

Return value:

  • ARKLS_SUCCESS if successful

  • ARKLS_MEM_NULL if the ARKStep memory was NULL

  • ARKLS_LMEM_NULL if the linear solver memory was NULL

Notes:

This routine must be called after the ARKLS linear solver interface has been initialized through a call to ARKStepSetLinearSolver().

By default, ARKLS uses an internal difference quotient function for the SUNMATRIX_DENSE and SUNMATRIX_BAND modules. If NULL is passed in for jac, this default is used. An error will occur if no jac is supplied when using other matrix types.

The function type ARKLsJacFn() is described in §2.4.4.

Deprecated since version 6.1.0: Use ARKodeSetJacFn() instead.

int ARKStepSetLinSysFn(void *arkode_mem, ARKLsLinSysFn linsys)

Specifies the linear system approximation routine to be used for the matrix-based solver with the ARKLS interface.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • linsys – name of user-supplied linear system approximation function.

Return value:

  • ARKLS_SUCCESS if successful

  • ARKLS_MEM_NULL if the ARKStep memory was NULL

  • ARKLS_LMEM_NULL if the linear solver memory was NULL

Notes:

This routine must be called after the ARKLS linear solver interface has been initialized through a call to ARKStepSetLinearSolver().

By default, ARKLS uses an internal linear system function that leverages the SUNMATRIX API to form the system \(M - \gamma J\). If NULL is passed in for linsys, this default is used.

The function type ARKLsLinSysFn() is described in §2.4.4.

Deprecated since version 6.1.0: Use ARKodeSetLinSysFn() instead.

int ARKStepSetMassFn(void *arkode_mem, ARKLsMassFn mass)

Specifies the mass matrix approximation routine to be used for the matrix-based solver with the ARKLS interface.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • mass – name of user-supplied mass matrix approximation function.

Return value:

  • ARKLS_SUCCESS if successful

  • ARKLS_MEM_NULL if the ARKStep memory was NULL

  • ARKLS_MASSMEM_NULL if the mass matrix solver memory was NULL

  • ARKLS_ILL_INPUT if an argument had an illegal value

Notes:

This routine must be called after the ARKLS mass matrix solver interface has been initialized through a call to ARKStepSetMassLinearSolver().

Since there is no default difference quotient function for mass matrices, mass must be non-NULL.

The function type ARKLsMassFn() is described in §2.4.4.

Deprecated since version 6.1.0: Use ARKodeSetMassFn() instead.

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • onoff – flag to enable (SUNTRUE) or disable (SUNFALSE) scaling

Return value:

  • ARKLS_SUCCESS if successful

  • ARKLS_MEM_NULL if the ARKStep memory was NULL

  • ARKLS_ILL_INPUT if the attached linear solver is not matrix-based

Notes:

Linear solution scaling is enabled by default when a matrix-based linear solver is attached.

Deprecated since version 6.1.0: Use ARKodeSetLinearSolutionScaling() instead.

2.4.7.1.8.5.3. Optional inputs for matrix-free SUNLinearSolver modules

int ARKStepSetJacTimes(void *arkode_mem, ARKLsJacTimesSetupFn jtsetup, ARKLsJacTimesVecFn jtimes)

Specifies the Jacobian-times-vector setup and product functions.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • jtsetup – user-defined Jacobian-vector setup function. Pass NULL if no setup is necessary.

  • jtimes – user-defined Jacobian-vector product function.

Return value:

  • ARKLS_SUCCESS if successful.

  • ARKLS_MEM_NULL if the ARKStep memory was NULL.

  • ARKLS_LMEM_NULL if the linear solver memory was NULL.

  • ARKLS_ILL_INPUT if an input has an illegal value.

  • ARKLS_SUNLS_FAIL if an error occurred when setting up the Jacobian-vector product in the SUNLinearSolver object used by the ARKLS interface.

Notes:

The default is to use an internal finite difference quotient for jtimes and to leave out jtsetup. If NULL is passed to jtimes, these defaults are used. A user may specify non-NULL jtimes and NULL jtsetup inputs.

This function must be called after the ARKLS system solver interface has been initialized through a call to ARKStepSetLinearSolver().

The function types ARKLsJacTimesSetupFn and ARKLsJacTimesVecFn are described in §2.4.4.

Deprecated since version 6.1.0: Use ARKodeSetJacTimes() instead.

int ARKStepSetJacTimesRhsFn(void *arkode_mem, ARKRhsFn jtimesRhsFn)

Specifies an alternative implicit right-hand side function for use in the internal Jacobian-vector product difference quotient approximation.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • jtimesRhsFn – the name of the C function (of type ARKRhsFn()) defining the alternative right-hand side function.

Return value:

  • ARKLS_SUCCESS if successful.

  • ARKLS_MEM_NULL if the ARKStep memory was NULL.

  • ARKLS_LMEM_NULL if the linear solver memory was NULL.

  • ARKLS_ILL_INPUT if an input has an illegal value.

Notes:

The default is to use the implicit right-hand side function provided to ARKStepCreate() in the internal difference quotient. If the input implicit right-hand side function is NULL, the default is used.

This function must be called after the ARKLS system solver interface has been initialized through a call to ARKStepSetLinearSolver().

Deprecated since version 6.1.0: Use ARKodeSetJacTimesRhsFn() instead.

int ARKStepSetMassTimes(void *arkode_mem, ARKLsMassTimesSetupFn mtsetup, ARKLsMassTimesVecFn mtimes, void *mtimes_data)

Specifies the mass matrix-times-vector setup and product functions.

Arguments:

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

  • ARKLS_SUCCESS if successful.

  • ARKLS_MEM_NULL if the ARKStep memory was NULL.

  • ARKLS_MASSMEM_NULL if the mass matrix solver memory was NULL.

  • ARKLS_ILL_INPUT if an input has an illegal value.

  • ARKLS_SUNLS_FAIL if an error occurred when setting up the mass-matrix-vector product in the SUNLinearSolver object used by the ARKLS interface.

Notes:

There is no default finite difference quotient for mtimes, so if using the ARKLS mass matrix solver interface with 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 ARKStepSetMassLinearSolver().

The function types ARKLsMassTimesSetupFn and ARKLsMassTimesVecFn are described in §2.4.4.

Deprecated since version 6.1.0: Use ARKodeSetMassTimes() instead.

2.4.7.1.8.5.4. Optional inputs for iterative SUNLinearSolver modules

int ARKStepSetPreconditioner(void *arkode_mem, ARKLsPrecSetupFn psetup, ARKLsPrecSolveFn psolve)

Specifies the user-supplied preconditioner setup and solve functions.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • psetup – user defined preconditioner setup function. Pass NULL if no setup is needed.

  • psolve – user-defined preconditioner solve function.

Return value:

  • ARKLS_SUCCESS if successful.

  • ARKLS_MEM_NULL if the ARKStep memory was NULL.

  • ARKLS_LMEM_NULL if the linear solver memory was NULL.

  • ARKLS_ILL_INPUT if an input has an illegal value.

  • ARKLS_SUNLS_FAIL if an error occurred when setting up preconditioning in the SUNLinearSolver object used by the ARKLS interface.

Notes:

The default is NULL for both arguments (i.e., no preconditioning).

This function must be called after the ARKLS system solver interface has been initialized through a call to ARKStepSetLinearSolver().

Both of the function types ARKLsPrecSetupFn() and ARKLsPrecSolveFn() are described in §2.4.4.

Deprecated since version 6.1.0: Use ARKodeSetPreconditioner() instead.

int ARKStepSetMassPreconditioner(void *arkode_mem, ARKLsMassPrecSetupFn psetup, ARKLsMassPrecSolveFn psolve)

Specifies the mass matrix preconditioner setup and solve functions.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • psetup – user defined preconditioner setup function. Pass NULL if no setup is to be done.

  • psolve – user-defined preconditioner solve function.

Return value:

  • ARKLS_SUCCESS if successful.

  • ARKLS_MEM_NULL if the ARKStep memory was NULL.

  • ARKLS_LMEM_NULL if the linear solver memory was NULL.

  • ARKLS_ILL_INPUT if an input has an illegal value.

  • ARKLS_SUNLS_FAIL if an error occurred when setting up preconditioning in the SUNLinearSolver object used by the ARKLS interface.

Notes:

This function must be called after the ARKLS mass matrix solver interface has been initialized through a call to ARKStepSetMassLinearSolver().

The default is NULL for both arguments (i.e. no preconditioning).

Both of the function types ARKLsMassPrecSetupFn() and ARKLsMassPrecSolveFn() are described in §2.4.4.

Deprecated since version 6.1.0: Use ARKodeSetMassPreconditioner() instead.

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • eplifac – linear convergence safety factor.

Return value:

  • ARKLS_SUCCESS if successful.

  • ARKLS_MEM_NULL if the ARKStep memory was NULL.

  • ARKLS_LMEM_NULL if the linear solver memory was NULL.

  • ARKLS_ILL_INPUT if an input has an illegal value.

Notes:

Passing a value eplifac \(\le 0\) indicates to use the default value of 0.05.

This function must be called after the ARKLS system solver interface has been initialized through a call to ARKStepSetLinearSolver().

Deprecated since version 6.1.0: Use ARKodeSetEpsLin() instead.

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • eplifac – linear convergence safety factor.

Return value:

  • ARKLS_SUCCESS if successful.

  • ARKLS_MEM_NULL if the ARKStep memory was NULL.

  • ARKLS_MASSMEM_NULL if the mass matrix solver memory was NULL.

  • ARKLS_ILL_INPUT if an input has an illegal value.

Notes:

This function must be called after the ARKLS mass matrix solver interface has been initialized through a call to ARKStepSetMassLinearSolver().

Passing a value eplifac \(\le 0\) indicates to use the default value of 0.05.

Deprecated since version 6.1.0: Use ARKodeSetMassEpsLin() instead.

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • nrmfac – the norm conversion factor. If nrmfac is:

    \(> 0\) then the provided value is used.

    \(= 0\) then the conversion factor is computed using the vector length i.e., nrmfac = sqrt(N_VGetLength(y)) (default).

    \(< 0\) then the conversion factor is computed using the vector dot product i.e., nrmfac = sqrt(N_VDotProd(v,v)) where all the entries of v are one.

Return value:

  • ARK_SUCCESS if successful.

  • ARK_MEM_NULL if the ARKStep memory was NULL.

Notes:

This function must be called after the ARKLS system solver interface has been initialized through a call to ARKStepSetLinearSolver().

Deprecated since version 6.1.0: Use ARKodeSetLSNormFactor() instead.

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • nrmfac – the norm conversion factor. If nrmfac is:

    \(> 0\) then the provided value is used.

    \(= 0\) then the conversion factor is computed using the vector length i.e., nrmfac = sqrt(N_VGetLength(y)) (default).

    \(< 0\) then the conversion factor is computed using the vector dot product i.e., nrmfac = sqrt(N_VDotProd(v,v)) where all the entries of v are one.

Return value:

  • ARK_SUCCESS if successful.

  • ARK_MEM_NULL if the ARKStep memory was NULL.

Notes:

This function must be called after the ARKLS mass matrix solver interface has been initialized through a call to ARKStepSetMassLinearSolver().

Deprecated since version 6.1.0: Use ARKodeSetMassLSNormFactor() instead.

2.4.7.1.8.6. Rootfinding optional input functions

int ARKStepSetRootDirection(void *arkode_mem, int *rootdir)

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • rootdir – state array of length nrtfn, the number of root functions \(g_i\) (the value of nrtfn was supplied in the call to ARKStepRootInit()). 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 ARKStep memory is NULL

  • ARK_ILL_INPUT if an argument had an illegal value

Notes:

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

Deprecated since version 6.1.0: Use ARKodeSetRootDirection() instead.

int ARKStepSetNoInactiveRootWarn(void *arkode_mem)

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory is NULL

Notes:

ARKStep will not report the initial conditions as a possible 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), ARKStep will issue a warning which can be disabled with this optional input function.

Deprecated since version 6.1.0: Use ARKodeSetNoInactiveRootWarn() instead.

2.4.7.1.9. Interpolated output function

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • t – the value of the independent variable at which the derivative is to be evaluated.

  • k – the derivative order requested.

  • dky – output vector (must be allocated by the user).

Return value:

  • ARK_SUCCESS if successful

  • ARK_BAD_K if k is not in the range {0,…, min(degree, kmax)}.

  • ARK_BAD_T if t is not in the interval \([t_n-h_n, t_n]\)

  • ARK_BAD_DKY if the dky vector was NULL

  • ARK_MEM_NULL if the ARKStep memory is NULL

Notes:

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

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

Deprecated since version 6.1.0: Use ARKodeGetDky() instead.

2.4.7.1.10. Optional output functions

2.4.7.1.10.1. Main solver optional output functions

int ARKStepGetWorkSpace(void *arkode_mem, long int *lenrw, long int *leniw)

Returns the ARKStep real and integer workspace sizes.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • lenrw – the number of sunrealtype values in the ARKStep workspace.

  • leniw – the number of integer values in the ARKStep workspace.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

Deprecated since version 6.1.0: Use ARKodeGetWorkSpace() instead.

int ARKStepGetNumSteps(void *arkode_mem, long int *nsteps)

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • nsteps – number of steps taken in the solver.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

Deprecated since version 6.1.0: Use ARKodeGetNumSteps() instead.

int ARKStepGetActualInitStep(void *arkode_mem, sunrealtype *hinused)

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • hinused – actual value of initial step size.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

Notes:

Even if the value of the initial integration step was specified by the user through a call to ARKStepSetInitStep(), this value may have been changed by ARKStep to ensure that the step size fell within the prescribed bounds \((h_{min} \le h_0 \le h_{max})\), or to satisfy the local error test condition, or to ensure convergence of the nonlinear solver.

Deprecated since version 6.1.0: Use ARKodeGetActualInitStep() instead.

int ARKStepGetLastStep(void *arkode_mem, sunrealtype *hlast)

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • hlast – step size taken on the last internal step.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

Deprecated since version 6.1.0: Use ARKodeGetLastStep() instead.

int ARKStepGetCurrentStep(void *arkode_mem, sunrealtype *hcur)

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • hcur – step size to be attempted on the next internal step.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

Deprecated since version 6.1.0: Use ARKodeGetCurrentStep() instead.

int ARKStepGetCurrentTime(void *arkode_mem, sunrealtype *tcur)

Returns the current internal time reached by the solver.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • tcur – current internal time reached.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

Deprecated since version 6.1.0: Use ARKodeGetCurrentTime() instead.

int ARKStepGetCurrentState(void *arkode_mem, N_Vector *ycur)

Returns the current internal solution reached by the solver.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • ycur – current internal solution.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

Notes:

Users should exercise extreme caution when using this function, as altering values of ycur may lead to undesirable behavior, depending on the particular use case and on when this routine is called.

Deprecated since version 6.1.0: Use ARKodeGetCurrentState() instead.

int ARKStepGetCurrentGamma(void *arkode_mem, sunrealtype *gamma)

Returns the current internal value of \(\gamma\) used in the implicit solver Newton matrix (see equation (2.51)).

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • gamma – current step size scaling factor in the Newton system.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

Deprecated since version 6.1.0: Use ARKodeGetCurrentGamma() instead.

int ARKStepGetTolScaleFactor(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 ARKStep memory block.

  • tolsfac – suggested scaling factor for user-supplied tolerances.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

Deprecated since version 6.1.0: Use ARKodeGetTolScaleFactor() instead.

int ARKStepGetErrWeights(void *arkode_mem, N_Vector eweight)

Returns the current error weight vector.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • eweight – solution error weights at the current time.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

Notes:

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

Deprecated since version 6.1.0: Use ARKodeGetErrWeights() instead.

int ARKStepGetResWeights(void *arkode_mem, N_Vector rweight)

Returns the current residual weight vector.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • rweight – residual error weights at the current time.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

Notes:

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

Deprecated since version 6.1.0: Use ARKodeGetResWeights() instead.

int ARKStepGetStepStats(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 ARKStep memory block.

  • nsteps – number of steps taken in the solver.

  • hinused – actual value of initial step size.

  • hlast – step size taken on the last internal step.

  • hcur – step size to be attempted on the next internal step.

  • tcur – current internal time reached.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

Deprecated since version 6.1.0: Use ARKodeGetStepStats() instead.

int ARKStepPrintAllStats(void *arkode_mem, FILE *outfile, SUNOutputFormat fmt)

Outputs all of the integrator, nonlinear solver, linear solver, and other statistics.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • outfile – pointer to output file.

  • fmt – the output format:

Return value:

  • ARK_SUCCESS – if the output was successfully.

  • ARK_MEM_NULL – if the ARKStep memory was NULL.

  • ARK_ILL_INPUT – if an invalid formatting option was provided.

Note

The 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 5.2.0.

Deprecated since version 6.1.0: Use ARKodePrintAllStats() instead.

char *ARKStepGetReturnFlagName(long int flag)

Returns the name of the ARKStep constant corresponding to flag. See ARKODE Constants.

Arguments:

  • flag – a return flag from an ARKStep function.

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

Deprecated since version 6.1.0: Use ARKodeGetReturnFlagName() instead.

int ARKStepGetNumExpSteps(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 ARKStep memory block.

  • expsteps – number of stability-limited steps taken in the solver.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

Deprecated since version 6.1.0: Use ARKodeGetNumExpSteps() instead.

int ARKStepGetNumAccSteps(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 ARKStep memory block.

  • accsteps – number of accuracy-limited steps taken in the solver.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

Deprecated since version 6.1.0: Use ARKodeGetNumAccSteps() instead.

int ARKStepGetNumStepAttempts(void *arkode_mem, long int *step_attempts)

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • step_attempts – number of steps attempted by solver.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

Deprecated since version 6.1.0: Use ARKodeGetNumStepAttempts() instead.

int ARKStepGetNumRhsEvals(void *arkode_mem, long int *nfe_evals, long int *nfi_evals)

Returns the number of calls to the user’s right-hand side functions, \(f^E\) and \(f^I\) (so far).

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • nfe_evals – number of calls to the user’s \(f^E(t,y)\) function.

  • nfi_evals – number of calls to the user’s \(f^I(t,y)\) function.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

Notes:

The nfi_evals value does not account for calls made to \(f^I\) by a linear solver or preconditioner module.

Deprecated since version 6.2.0: Use ARKodeGetNumRhsEvals() instead.

int ARKStepGetNumErrTestFails(void *arkode_mem, long int *netfails)

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • netfails – number of error test failures.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

Deprecated since version 6.1.0: Use ARKodeGetNumErrTestFails() instead.

int ARKStepGetNumStepSolveFails(void *arkode_mem, long int *ncnf)

Returns the number of failed steps due to a nonlinear solver failure (so far).

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • ncnf – number of step failures.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

Deprecated since version 6.1.0: Use ARKodeGetNumStepSolveFails() instead.

int ARKStepGetCurrentButcherTables(void *arkode_mem, ARKodeButcherTable *Bi, ARKodeButcherTable *Be)

Returns the explicit and implicit Butcher tables currently in use by the solver.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • Bi – pointer to the implicit Butcher table structure.

  • Be – pointer to the explicit Butcher table structure.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

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

typedef struct ARKStepButcherTableMem {

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

} *ARKStepButcherTable;

For more details see §2.5.

int ARKStepGetEstLocalErrors(void *arkode_mem, N_Vector ele)

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • ele – vector of estimated local truncation errors.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

Notes:

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

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

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

Deprecated since version 6.1.0: Use ARKodeGetEstLocalErrors() instead.

int ARKStepGetTimestepperStats(void *arkode_mem, long int *expsteps, long int *accsteps, long int *step_attempts, long int *nfe_evals, long int *nfi_evals, long int *nlinsetups, long int *netfails)

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

Arguments:

  • arkode_mem – pointer to the ARKStep 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.

  • nfe_evals – number of calls to the user’s \(f^E(t,y)\) function.

  • nfi_evals – number of calls to the user’s \(f^I(t,y)\) function.

  • nlinsetups – number of linear solver setup calls made.

  • netfails – number of error test failures.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

int ARKStepGetNumConstrFails(void *arkode_mem, long int *nconstrfails)

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • nconstrfails – number of constraint test failures.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

Deprecated since version 6.1.0: Use ARKodeGetNumConstrFails() instead.

int ARKStepGetUserData(void *arkode_mem, void **user_data)

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • user_data – memory reference to a user data pointer

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

Added in version 5.3.0.

Deprecated since version 6.1.0: Use ARKodeGetUserData() instead.

2.4.7.1.10.2. Implicit solver optional output functions

int ARKStepGetNumLinSolvSetups(void *arkode_mem, long int *nlinsetups)

Returns the number of calls made to the linear solver’s setup routine (so far).

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • nlinsetups – number of linear solver setup calls made.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

Note: This is only accumulated for the “life” of the nonlinear solver object; the counter is reset whenever a new nonlinear solver module is “attached” to ARKStep, or when ARKStep is resized.

Deprecated since version 6.1.0: Use ARKodeGetNumLinSolvSetups() instead.

int ARKStepGetNumNonlinSolvIters(void *arkode_mem, long int *nniters)

Returns the number of nonlinear solver iterations performed (so far).

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • nniters – number of nonlinear iterations performed.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

  • ARK_NLS_OP_ERR if the SUNNONLINSOL object returned a failure flag

Note: This is only accumulated for the “life” of the nonlinear solver object; the counter is reset whenever a new nonlinear solver module is “attached” to ARKStep, or when ARKStep is resized.

Deprecated since version 6.1.0: Use ARKodeGetNumNonlinSolvIters() instead.

int ARKStepGetNumNonlinSolvConvFails(void *arkode_mem, long int *nncfails)

Returns the number of nonlinear solver convergence failures that have occurred (so far).

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • nncfails – number of nonlinear convergence failures.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

Note: This is only accumulated for the “life” of the nonlinear solver object; the counter is reset whenever a new nonlinear solver module is “attached” to ARKStep, or when ARKStep is resized.

Deprecated since version 6.1.0: Use ARKodeGetNumNonlinSolvConvFails() instead.

int ARKStepGetNonlinSolvStats(void *arkode_mem, long int *nniters, long int *nncfails)

Returns all of the nonlinear solver statistics in a single call.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • nniters – number of nonlinear iterations performed.

  • nncfails – number of nonlinear convergence failures.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

  • ARK_NLS_OP_ERR if the SUNNONLINSOL object returned a failure flag

Note: This is only accumulated for the “life” of the nonlinear solver object; the counters are reset whenever a new nonlinear solver module is “attached” to ARKStep, or when ARKStep is resized.

Deprecated since version 6.1.0: Use ARKodeGetNonlinSolvStats() instead.

2.4.7.1.10.3. Rootfinding optional output functions

int ARKStepGetRootInfo(void *arkode_mem, int *rootsfound)

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • rootsfound – array of length nrtfn with the indices of the user functions \(g_i\) found to have a root (the value of nrtfn was supplied in the call to ARKStepRootInit()). For \(i = 0 \ldots\) 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 ARKStep memory was NULL

Notes:

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

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

Deprecated since version 6.1.0: Use ARKodeGetRootInfo() instead.

int ARKStepGetNumGEvals(void *arkode_mem, long int *ngevals)

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • ngevals – number of calls made to \(g\) so far.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

Deprecated since version 6.1.0: Use ARKodeGetNumGEvals() instead.

2.4.7.1.10.4. Linear solver interface optional output functions

int ARKStepGetJac(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 ARKStep memory structure

  • J – the Jacobian matrix

Return values:

  • ARKLS_SUCCESS – the output value has been successfully set

  • ARKLS_MEM_NULL – arkode_mem was NULL

  • ARKLS_LMEM_NULL – the linear solver interface has not been initialized

Warning

This function is provided for debugging purposes and the values in the returned matrix should not be altered.

Deprecated since version 6.1.0: Use ARKodeGetJac() instead.

int ARKStepGetJacTime(void *arkode_mem, sunrealtype *t_J)

Returns the time at which the internally stored copy of the Jacobian matrix of the ODE implicit right-hand side function was evaluated.

Parameters:

  • arkode_mem – the ARKStep memory structure

  • t_J – the time at which the Jacobian was evaluated

Return values:

  • ARKLS_SUCCESS – the output value has been successfully set

  • ARKLS_MEM_NULL – arkode_mem was NULL

  • ARKLS_LMEM_NULL – the linear solver interface has not been initialized

Deprecated since version 6.1.0: Use ARKodeGetJacTime() instead.

int ARKStepGetJacNumSteps(void *arkode_mem, long int *nst_J)

Returns the value of the internal step counter at which the internally stored copy of the Jacobian matrix of the ODE implicit right-hand side function was evaluated.

Parameters:

  • arkode_mem – the ARKStep memory structure

  • nst_J – the value of the internal step counter at which the Jacobian was evaluated

Return values:

  • ARKLS_SUCCESS – the output value has been successfully set

  • ARKLS_MEM_NULL – arkode_mem was NULL

  • ARKLS_LMEM_NULL – the linear solver interface has not been initialized

Deprecated since version 6.1.0: Use ARKodeGetJacNumSteps() instead.

int ARKStepGetLinWorkSpace(void *arkode_mem, long int *lenrwLS, long int *leniwLS)

Returns the real and integer workspace used by the ARKLS linear solver interface.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • lenrwLS – the number of sunrealtype values in the ARKLS workspace.

  • leniwLS – the number of integer values in the ARKLS workspace.

Return value:

  • ARKLS_SUCCESS if successful

  • ARKLS_MEM_NULL if the ARKStep memory was NULL

  • ARKLS_LMEM_NULL if the linear solver memory was NULL

Notes:

The workspace requirements reported by this routine correspond only to memory allocated within this interface and to memory allocated by the SUNLinearSolver object attached to it. The template Jacobian matrix allocated by the user outside of ARKLS is not included in this report.

In a parallel setting, the above values are global (i.e. summed over all processors).

Deprecated since version 6.1.0: Use ARKodeGetLinWorkSpace() instead.

int ARKStepGetNumJacEvals(void *arkode_mem, long int *njevals)

Returns the number of Jacobian evaluations.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • njevals – number of Jacobian evaluations.

Return value:

  • ARKLS_SUCCESS if successful

  • ARKLS_MEM_NULL if the ARKStep memory was NULL

  • ARKLS_LMEM_NULL if the linear solver memory was NULL

Note: This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new linear solver module is “attached” to ARKStep, or when ARKStep is resized.

Deprecated since version 6.1.0: Use ARKodeGetNumJacEvals() instead.

int ARKStepGetNumPrecEvals(void *arkode_mem, long int *npevals)

Returns the total number of preconditioner evaluations, i.e. the number of calls made to psetup with jok = SUNFALSE and that returned *jcurPtr = SUNTRUE.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • npevals – the current number of calls to psetup.

Return value:

  • ARKLS_SUCCESS if successful

  • ARKLS_MEM_NULL if the ARKStep memory was NULL

  • ARKLS_LMEM_NULL if the linear solver memory was NULL

Note: This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new linear solver module is “attached” to ARKStep, or when ARKStep is resized.

Deprecated since version 6.1.0: Use ARKodeGetNumPrecEvals() instead.

int ARKStepGetNumPrecSolves(void *arkode_mem, long int *npsolves)

Returns the number of calls made to the preconditioner solve function, psolve.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • npsolves – the number of calls to psolve.

Return value:

  • ARKLS_SUCCESS if successful

  • ARKLS_MEM_NULL if the ARKStep memory was NULL

  • ARKLS_LMEM_NULL if the linear solver memory was NULL

Note: This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new linear solver module is “attached” to ARKStep, or when ARKStep is resized.

Deprecated since version 6.1.0: Use ARKodeGetNumPrecSolves() instead.

int ARKStepGetNumLinIters(void *arkode_mem, long int *nliters)

Returns the cumulative number of linear iterations.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • nliters – the current number of linear iterations.

Return value:

  • ARKLS_SUCCESS if successful

  • ARKLS_MEM_NULL if the ARKStep memory was NULL

  • ARKLS_LMEM_NULL if the linear solver memory was NULL

Note: This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new linear solver module is “attached” to ARKStep, or when ARKStep is resized.

Deprecated since version 6.1.0: Use ARKodeGetNumLinIters() instead.

int ARKStepGetNumLinConvFails(void *arkode_mem, long int *nlcfails)

Returns the cumulative number of linear convergence failures.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • nlcfails – the current number of linear convergence failures.

Return value:

  • ARKLS_SUCCESS if successful

  • ARKLS_MEM_NULL if the ARKStep memory was NULL

  • ARKLS_LMEM_NULL if the linear solver memory was NULL

Note: This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new linear solver module is “attached” to ARKStep, or when ARKStep is resized.

Deprecated since version 6.1.0: Use ARKodeGetNumLinConvFails() instead.

int ARKStepGetNumJTSetupEvals(void *arkode_mem, long int *njtsetup)

Returns the cumulative number of calls made to the user-supplied Jacobian-vector setup function, jtsetup.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • njtsetup – the current number of calls to jtsetup.

Return value:

  • ARKLS_SUCCESS if successful

  • ARKLS_MEM_NULL if the ARKStep memory was NULL

  • ARKLS_LMEM_NULL if the linear solver memory was NULL

Note: This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new linear solver module is “attached” to ARKStep, or when ARKStep is resized.

Deprecated since version 6.1.0: Use ARKodeGetNumJTSetupEvals() instead.

int ARKStepGetNumJtimesEvals(void *arkode_mem, long int *njvevals)

Returns the cumulative number of calls made to the Jacobian-vector product function, jtimes.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • njvevals – the current number of calls to jtimes.

Return value:

  • ARKLS_SUCCESS if successful

  • ARKLS_MEM_NULL if the ARKStep memory was NULL

  • ARKLS_LMEM_NULL if the linear solver memory was NULL

Note: This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new linear solver module is “attached” to ARKStep, or when ARKStep is resized.

Deprecated since version 6.1.0: Use ARKodeGetNumJtimesEvals() instead.

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • nfevalsLS – the number of calls to the user implicit right-hand side function.

Return value:

  • ARKLS_SUCCESS if successful

  • ARKLS_MEM_NULL if the ARKStep memory was NULL

  • ARKLS_LMEM_NULL if the linear solver memory was NULL

Notes:

The value nfevalsLS is incremented only if the default internal difference quotient function is used.

This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new linear solver module is “attached” to ARKStep, or when ARKStep is resized.

Deprecated since version 6.1.0: Use ARKodeGetNumLinRhsEvals() instead.

int ARKStepGetLastLinFlag(void *arkode_mem, long int *lsflag)

Returns the last return value from an ARKLS routine.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • lsflag – the value of the last return flag from an ARKLS function.

Return value:

  • ARKLS_SUCCESS if successful

  • ARKLS_MEM_NULL if the ARKStep memory was NULL

  • ARKLS_LMEM_NULL if the linear solver memory was NULL

Notes:

If the ARKLS setup function failed when using the SUNLINSOL_DENSE or SUNLINSOL_BAND modules, then the value of lsflag is equal to the column index (numbered from one) at which a zero diagonal element was encountered during the LU factorization of the (dense or banded) Jacobian matrix. For all other failures, lsflag is negative.

Otherwise, if the ARKLS setup function failed (ARKStepEvolve() returned ARK_LSETUP_FAIL), then lsflag will be SUNLS_PSET_FAIL_UNREC, SUNLS_ASET_FAIL_UNREC or SUN_ERR_EXT_FAIL.

If the ARKLS solve function failed (ARKStepEvolve() returned ARK_LSOLVE_FAIL), then lsflag contains the error return flag from the SUNLinearSolver object, which will be one of: SUN_ERR_ARG_CORRUPTRRUPT, indicating that the SUNLinearSolver memory is NULL; 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.

Deprecated since version 6.1.0: Use ARKodeGetLastLinFlag() instead.

char *ARKStepGetLinReturnFlagName(long int lsflag)

Returns the name of the ARKLS constant corresponding to lsflag.

Arguments:

  • lsflag – a return flag from an ARKLS function.

Return value: The return value is a string containing the name of the corresponding constant. If using the SUNLINSOL_DENSE or SUNLINSOL_BAND modules, then if 1 \(\le\) lsflag \(\le n\) (LU factorization failed), this routine returns “NONE”.

Deprecated since version 6.1.0: Use ARKodeGetLinReturnFlagName() instead.

int ARKStepGetMassWorkSpace(void *arkode_mem, long int *lenrwMLS, long int *leniwMLS)

Returns the real and integer workspace used by the ARKLS mass matrix linear solver interface.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • lenrwMLS – the number of sunrealtype values in the ARKLS mass solver workspace.

  • leniwMLS – the number of integer values in the ARKLS mass solver workspace.

Return value:

  • ARKLS_SUCCESS if successful

  • ARKLS_MEM_NULL if the ARKStep memory was NULL

  • ARKLS_LMEM_NULL if the linear solver memory was NULL

Notes:

The workspace requirements reported by this routine correspond only to memory allocated within this interface and to memory allocated by the SUNLinearSolver object attached to it. The template mass matrix allocated by the user outside of ARKLS is not included in this report.

In a parallel setting, the above values are global (i.e. summed over all processors).

Deprecated since version 6.1.0: Use ARKodeGetMassWorkSpace() instead.

int ARKStepGetNumMassSetups(void *arkode_mem, long int *nmsetups)

Returns the number of calls made to the ARKLS mass matrix solver ‘setup’ routine; these include all calls to the user-supplied mass-matrix constructor function.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • nmsetups – number of calls to the mass matrix solver setup routine.

Return value:

  • ARKLS_SUCCESS if successful

  • ARKLS_MEM_NULL if the ARKStep memory was NULL

  • ARKLS_LMEM_NULL if the linear solver memory was NULL

Note: This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new mass-matrix linear solver module is “attached” to ARKStep, or when ARKStep is resized.

Deprecated since version 6.1.0: Use ARKodeGetNumMassSetups() instead.

int ARKStepGetNumMassMultSetups(void *arkode_mem, long int *nmvsetups)

Returns the number of calls made to the ARKLS mass matrix ‘matvec setup’ (matrix-based solvers) routine.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • nmvsetups – number of calls to the mass matrix matrix-times-vector setup routine.

Return value:

  • ARKLS_SUCCESS if successful

  • ARKLS_MEM_NULL if the ARKStep memory was NULL

  • ARKLS_LMEM_NULL if the linear solver memory was NULL

Note: This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new mass-matrix linear solver module is “attached” to ARKStep, or when ARKStep is resized.

Deprecated since version 6.1.0: Use ARKodeGetNumMassMultSetups() instead.

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • nmmults – number of calls to the mass matrix solver matrix-times-vector routine.

Return value:

  • ARKLS_SUCCESS if successful

  • ARKLS_MEM_NULL if the ARKStep memory was NULL

  • ARKLS_LMEM_NULL if the linear solver memory was NULL

Note: This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new mass-matrix linear solver module is “attached” to ARKStep, or when ARKStep is resized.

Deprecated since version 6.1.0: Use ARKodeGetNumMassMult() instead.

int ARKStepGetNumMassSolves(void *arkode_mem, long int *nmsolves)

Returns the number of calls made to the ARKLS mass matrix solver ‘solve’ routine.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • nmsolves – number of calls to the mass matrix solver solve routine.

Return value:

  • ARKLS_SUCCESS if successful

  • ARKLS_MEM_NULL if the ARKStep memory was NULL

  • ARKLS_LMEM_NULL if the linear solver memory was NULL

Note: This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new mass-matrix linear solver module is “attached” to ARKStep, or when ARKStep is resized.

Deprecated since version 6.1.0: Use ARKodeGetNumMassSolves() instead.

int ARKStepGetNumMassPrecEvals(void *arkode_mem, long int *nmpevals)

Returns the total number of mass matrix preconditioner evaluations, i.e. the number of calls made to psetup.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • nmpevals – the current number of calls to psetup.

Return value:

  • ARKLS_SUCCESS if successful

  • ARKLS_MEM_NULL if the ARKStep memory was NULL

  • ARKLS_LMEM_NULL if the linear solver memory was NULL

Note: This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new mass-matrix linear solver module is “attached” to ARKStep, or when ARKStep is resized.

Deprecated since version 6.1.0: Use ARKodeGetNumMassPrecEvals() instead.

int ARKStepGetNumMassPrecSolves(void *arkode_mem, long int *nmpsolves)

Returns the number of calls made to the mass matrix preconditioner solve function, psolve.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • nmpsolves – the number of calls to psolve.

Return value:

  • ARKLS_SUCCESS if successful

  • ARKLS_MEM_NULL if the ARKStep memory was NULL

  • ARKLS_LMEM_NULL if the linear solver memory was NULL

Note: This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new mass-matrix linear solver module is “attached” to ARKStep, or when ARKStep is resized.

Deprecated since version 6.1.0: Use ARKodeGetNumMassPrecSolves() instead.

int ARKStepGetNumMassIters(void *arkode_mem, long int *nmiters)

Returns the cumulative number of mass matrix solver iterations.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • nmiters – the current number of mass matrix solver linear iterations.

Return value:

  • ARKLS_SUCCESS if successful

  • ARKLS_MEM_NULL if the ARKStep memory was NULL

  • ARKLS_LMEM_NULL if the linear solver memory was NULL

Note: This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new mass-matrix linear solver module is “attached” to ARKStep, or when ARKStep is resized.

Deprecated since version 6.1.0: Use ARKodeGetNumMassIters() instead.

int ARKStepGetNumMassConvFails(void *arkode_mem, long int *nmcfails)

Returns the cumulative number of mass matrix solver convergence failures.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • nmcfails – the current number of mass matrix solver convergence failures.

Return value:

  • ARKLS_SUCCESS if successful

  • ARKLS_MEM_NULL if the ARKStep memory was NULL

  • ARKLS_LMEM_NULL if the linear solver memory was NULL

Note: This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new mass-matrix linear solver module is “attached” to ARKStep, or when ARKStep is resized.

Deprecated since version 6.1.0: Use ARKodeGetNumMassConvFails() instead.

int ARKStepGetNumMTSetups(void *arkode_mem, long int *nmtsetup)

Returns the cumulative number of calls made to the user-supplied mass-matrix-vector product setup function, mtsetup.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • nmtsetup – the current number of calls to mtsetup.

Return value:

  • ARKLS_SUCCESS if successful

  • ARKLS_MEM_NULL if the ARKStep memory was NULL

  • ARKLS_LMEM_NULL if the linear solver memory was NULL

Note: This is only accumulated for the “life” of the linear solver object; the counter is reset whenever a new mass-matrix linear solver module is “attached” to ARKStep, or when ARKStep is resized.

Deprecated since version 6.1.0: Use ARKodeGetNumMTSetups() instead.

int ARKStepGetLastMassFlag(void *arkode_mem, long int *mlsflag)

Returns the last return value from an ARKLS mass matrix interface routine.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • mlsflag – the value of the last return flag from an ARKLS mass matrix solver interface function.

Return value:

  • ARKLS_SUCCESS if successful

  • ARKLS_MEM_NULL if the ARKStep memory was NULL

  • ARKLS_LMEM_NULL if the linear solver memory was NULL

Notes:

The values of msflag for each of the various solvers will match those described above for the function ARKStepGetLastLinFlag().

Deprecated since version 6.1.0: Use ARKodeGetLastMassFlag() instead.

2.4.7.1.10.5. General usability functions

int ARKStepWriteParameters(void *arkode_mem, FILE *fp)

Outputs all ARKStep solver parameters to the provided file pointer.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • fp – pointer to use for printing the solver parameters.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

Notes:

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

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

Deprecated since version 6.1.0: Use ARKodeWriteParameters() instead.

int ARKStepWriteButcher(void *arkode_mem, FILE *fp)

Outputs the current Butcher table(s) to the provided file pointer.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • fp – pointer to use for printing the Butcher table(s).

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

Notes:

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

If ARKStep is currently configured to run in purely explicit or purely implicit mode, this will output a single Butcher table; if configured to run an ImEx method then both tables will be output.

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

Deprecated since version 6.1.0: Use ARKStepGetCurrentButcherTables() and ARKodeButcherTable_Write() instead.

2.4.7.1.11. ARKStep re-initialization function

To reinitialize the ARKStep module for the solution of a new problem, where a prior call to ARKStepCreate() has been made, the user must call the function ARKStepReInit(). The new problem must have the same size as the previous one. This routine retains the current settings for all ARKstep module options and performs the same input checking and initializations that are done in ARKStepCreate(), but it performs no memory allocation as it assumes that the existing internal memory is sufficient for the new problem. A call to this 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 ARKStepSetStopTime(). Following a successful call to ARKStepReInit(), call ARKStepEvolve() again for the solution of the new problem.

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

When using the ARKStep time-stepping module, if there are changes to the linear solver specifications, the user should make the appropriate calls to either the linear solver objects themselves, or to the ARKLS interface routines, as described in §2.4.7.1.3. Otherwise, all solver inputs set previously remain in effect.

One important use of the ARKStepReInit() function is in the treating of jump discontinuities in the RHS functions. Except in cases of fairly small jumps, it is usually more efficient to stop at each point of discontinuity and restart the integrator with a readjusted ODE model, using a call to ARKStepReInit(). To stop when the location of the discontinuity is known, simply make that location a value of tout. To stop when the location of the discontinuity is determined by the solution, use the rootfinding feature. In either case, it is critical that the RHS functions not incorporate the discontinuity, but rather have a smooth extension over the discontinuity, so that the step across it (and subsequent rootfinding, if used) can be done efficiently. Then use a switch within the RHS functions (communicated through user_data) that can be flipped between the stopping of the integration and the restart, so that the restarted problem uses the new values (which have jumped). Similar comments apply if there is to be a jump in the dependent variable vector.

int ARKStepReInit(void *arkode_mem, ARKRhsFn fe, ARKRhsFn fi, sunrealtype t0, N_Vector y0)

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • fe – the name of the C function (of type ARKRhsFn()) defining the explicit portion of the right-hand side function in \(M\, \dot{y} = f^E(t,y) + f^I(t,y)\).

  • fi – the name of the C function (of type ARKRhsFn()) defining the implicit portion of the right-hand side function in \(M\, \dot{y} = f^E(t,y) + f^I(t,y)\).

  • t0 – the initial value of \(t\).

  • y0 – the initial condition vector \(y(t_0)\).

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

  • ARK_MEM_FAIL if a memory allocation failed

  • ARK_ILL_INPUT if an argument had an illegal value.

Notes:

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

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

2.4.7.1.12. ARKStep reset function

int ARKStepReset(void *arkode_mem, sunrealtype tR, N_Vector yR)

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

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • tR – the value of the independent variable \(t\).

  • yR – the value of the dependent variable vector \(y(t_R)\).

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

  • ARK_MEM_FAIL if a memory allocation failed

  • ARK_ILL_INPUT if an argument had an illegal value.

Notes:

By default the next call to ARKStepEvolve() will use the step size computed by ARKStep prior to calling ARKStepReset(). To set a different step size or have ARKStep estimate a new step size use ARKStepSetInitStep().

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

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

Deprecated since version 6.1.0: Use ARKodeReset() instead.

2.4.7.1.13. ARKStep system resize function

int ARKStepResize(void *arkode_mem, N_Vector yR, sunrealtype hscale, sunrealtype tR, ARKVecResizeFn resize, void *resize_data)

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

Arguments:

  • arkode_mem – pointer to the ARKStep 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 ARKStep vectors.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_NULL if the ARKStep memory was NULL

  • ARK_NO_MALLOC if arkode_mem was not allocated.

  • ARK_ILL_INPUT if an argument had an illegal value.

Notes:

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

If inequality constraint checking is enabled a call to ARKStepResize() will disable constraint checking. A call to ARKStepSetConstraints() 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 ARKStepResize(). Moreover, the existing ARKLS interface should then be deleted and recreated by attaching the updated SUNLinearSolver (and possibly SUNMatrix) object(s) through calls to ARKStepSetLinearSolver(), and ARKStepSetMassLinearSolver().

If any 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 ARKStepResize(), so the new absolute tolerance vector should be re-set following each call to ARKStepResize() through a new call to ARKStepSVtolerances() and possibly ARKStepResVtolerance() if applicable.

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

Example codes:

  • examples/arkode/C_serial/ark_heat1D_adapt.c

Deprecated since version 6.1.0: Use ARKodeResize() instead.

2.4.7.1.14. Interfacing with MRIStep

When using ARKStep as the inner (fast) integrator with MRIStep, the utility function ARKStepCreateMRIStepInnerStepper() should be used to wrap an ARKStep memory block as an MRIStepInnerStepper.

int ARKStepCreateMRIStepInnerStepper(void *inner_arkode_mem, MRIStepInnerStepper *stepper)

Wraps an ARKStep memory block as an MRIStepInnerStepper for use with MRIStep.

Arguments:

  • arkode_mem – pointer to the ARKStep memory block.

  • stepper – the MRIStepInnerStepper object.

Return value:

  • ARK_SUCCESS if successful

  • ARK_MEM_FAIL if a memory allocation failed

  • ARK_ILL_INPUT if an argument had an illegal value.

Example usage:
/* fast (inner) and slow (outer) ARKODE objects */
void *inner_arkode_mem = NULL;
void *outer_arkode_mem = NULL;

/* MRIStepInnerStepper to wrap the inner (fast) ARKStep object */
MRIStepInnerStepper stepper = NULL;

/* create an ARKStep object, setting fast (inner) right-hand side
   functions and the initial condition */
inner_arkode_mem = ARKStepCreate(ffe, ffi, t0, y0, sunctx);

/* setup ARKStep */
. . .

/* create MRIStepInnerStepper wrapper for the ARKStep memory block */
flag = ARKStepCreateMRIStepInnerStepper(inner_arkode_mem, &stepper);

/* create an MRIStep object, setting the slow (outer) right-hand side
   functions and the initial condition */
outer_arkode_mem = MRIStepCreate(fse, fsi, t0, y0, stepper, sunctx);
Example codes:

  • examples/arkode/CXX_parallel/ark_diffusion_reaction_p.cpp

Deprecated since version 6.2.0: Use ARKodeCreateMRIStepInnerStepper() instead.