13.1. The SUNStepper API

Added in version 7.2.0.

As with other SUNDIALS classes, the SUNStepper abstract base class is implemented using a C structure containing a content pointer to the derived class member data and a structure of function pointers to the derived class implementations of the virtual methods.

type SUNStepper

An object for solving the IVP (13.1).

The actual definition of the SUNStepper structure is kept private to allow for the object internals to change without impacting user code. The following sections describe the base class methods and the virtual methods that a must be provided by a derived class.

13.1.1. Base Class Methods

This section describes methods provided by the SUNStepper abstract base class that aid the user in implementing derived classes. This includes functions for creating and destroying a generic base class object, attaching and retrieving the derived class content pointer, and setting function pointers to derived class method implementations.

13.1.1.1. Creating and Destroying an Object

In addition to creating an empty SUNStepper using SUNStepper_Create() described below, there is the ARKodeCreateSUNStepper() function to construct a SUNStepper from an ARKODE integrator.

SUNErrCode SUNStepper_Create(SUNContext sunctx, SUNStepper *stepper)

This function creates a SUNStepper object to which a user should attach the member data (content) pointer and method function pointers.

Parameters:

• sunctx – the SUNDIALS simulation context.

• stepper – a pointer to a stepper object.

Returns:

A SUNErrCode indicating success or failure.

Example usage:

/* create an instance of the base class */
SUNStepper stepper = NULL;
SUNErrCode err = SUNStepper_Create(sunctx, &stepper);

Note

See §13.1.1.4 and §13.1.1.6 for details on how to attach member data and method function pointers.

SUNErrCode SUNStepper_Destroy(SUNStepper *stepper)

This function frees memory allocated by the SUNStepper base class and uses the function pointer optionally specified with SUNStepper_SetDestroyFn() to free the content.

Parameters:

• stepper – a pointer to a stepper object.

Returns:

A SUNErrCode indicating success or failure.

Note

This function only frees memory allocated within the base class and the base class structure itself. The user is responsible for freeing any memory allocated for the member data (content).

13.1.1.2. Stepping Functions

SUNErrCode SUNStepper_Evolve(SUNStepper stepper, sunrealtype tout, N_Vector vret, sunrealtype *tret)

This function evolves the ODE (13.1) towards the time tout and stores the solution at time tret in vret.

Parameters:

• stepper – the stepper object.

• tout – the time to evolve towards.

• vret – on output, the state at time tret.

• tret – the time corresponding to the output value vret.

Returns:

A SUNErrCode indicating success or failure.

SUNErrCode SUNStepper_OneStep(SUNStepper stepper, sunrealtype tout, N_Vector vret, sunrealtype *tret)

This function evolves the ODE (13.1) one timestep towards the time tout and stores the solution at time tret in vret.

Parameters:

• stepper – the stepper object.

• tout – the time to evolve towards.

• vret – on output, the state at time tret.

• tret – the time corresponding to the output value vret.

Returns:

A SUNErrCode indicating success or failure.

SUNErrCode SUNStepper_FullRhs(SUNStepper stepper, sunrealtype t, N_Vector v, N_Vector f, SUNFullRhsMode mode)

This function computes the full right-hand side function of the ODE, \(f(t, v) + r(t)\) in (13.1) for a given value of the independent variable t and state vector v.

Parameters:

• stepper – the stepper object.

• t – the current value of the independent variable.

• v – the current value of the dependent variable vector.

• f – the output vector for the ODE right-hand side, \(f(t, v) + r(t)\), in (13.1).

• mode – the purpose of the right-hand side evaluation.

Returns:

A SUNErrCode indicating success or failure.

SUNErrCode SUNStepper_ReInit(SUNStepper stepper, sunrealtype t0, N_Vector v0)

This function reinitalizes the stepper to solve a new problem with the given initial condition and clears all counters.

Parameters:

• stepper – the stepper object.

• t0 – the value of the independent variable \(t_0\).

• v0 – the value of the dependent variable vector \(v(t_0)\).

Returns:

A SUNErrCode indicating success or failure.

Added in version 7.3.0.

SUNErrCode SUNStepper_Reset(SUNStepper stepper, sunrealtype tR, N_Vector vR)

This function resets the stepper state to the provided independent variable value and dependent variable vector.

Parameters:

• stepper – the stepper object.

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

• vR – the value of the dependent variable vector \(v(t_R)\).

Returns:

A SUNErrCode indicating success or failure.

SUNErrCode SUNStepper_ResetCheckpointIndex(SUNStepper stepper, suncountertype ckptIdxR)

This function resets the index at which new checkpoints will be inserted to ckptIdxR.

Parameters:

• stepper – the stepper object.

• ckptIdxR – the step index to begin checkpointing from

Returns:

A SUNErrCode indicating success or failure.

Added in version 7.3.0.

SUNErrCode SUNStepper_SetStopTime(SUNStepper stepper, sunrealtype tstop)

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

Parameters:

• stepper – the stepper object.

• tstop – stopping time for the stepper.

Returns:

A SUNErrCode indicating success or failure.

SUNErrCode SUNStepper_SetStepDirection(SUNStepper stepper, sunrealtype stepdir)

This function specifies the direction of integration (forward or backward).

Parameters:

• stepper – the stepper object.

• stepdir – value whose sign determines the direction. A positive value selects forward integration, a negative value selects backward integration, and zero leaves the current direction unchanged.

Returns:

A SUNErrCode indicating success or failure.

SUNErrCode SUNStepper_SetForcing(SUNStepper stepper, sunrealtype tshift, sunrealtype tscale, N_Vector *forcing, int nforcing)

This function sets the data necessary to compute the forcing term (13.2). This includes the shift and scaling factors for the normalized time \(\frac{t - t_{\text{shift}}}{t_{\text{scale}}}\) and the array of polynomial coefficient vectors \(\widehat{f}_k\).

Parameters:

• stepper – a stepper object.

• tshift – the time shift to apply to the current time when computing the forcing, \(t_{\text{shift}}\).

• tscale – the time scaling to apply to the current time when computing the forcing, \(t_{\text{scale}}\).

• forcing – a pointer to an array of forcing vectors, \(\widehat{f}_k\).

• nforcing – the number of forcing vectors, \(n_{\text{forcing}}\). A value of 0 effectively eliminates the forcing term.

Returns:

A SUNErrCode indicating success or failure.

Note

When integrating the ODE (13.1) the SUNStepper is responsible for evaluating ODE right-hand side function \(f(t, v)\) as well as computing and applying the forcing term (13.2) to obtain the full right-hand side of the ODE (13.1).

SUNErrCode SUNStepper_GetNumSteps(SUNStepper stepper, suncountertype *nst)

This function gets the number of successful time steps taken by the stepper since it was last initialized.

Parameters:

• stepper – the stepper object.

• nst – on output, the number of time steps.

Returns:

A SUNErrCode indicating success or failure.

Added in version 7.3.0.

13.1.1.3. The Right-Hand Side Evaluation Mode

enum SUNFullRhsMode

A flag indicating the purpose of a right-hand side function evaluation.

enumerator SUN_FULLRHS_START

Evaluate at the beginning of the simulation.

enumerator SUN_FULLRHS_END

Evaluate at the end of a successful step.

enumerator SUN_FULLRHS_OTHER

Evaluate elsewhere, e.g., for dense output.

13.1.1.4. Attaching and Accessing the Content Pointer

SUNErrCode SUNStepper_SetContent(SUNStepper stepper, void *content)

This function attaches a member data (content) pointer to a SUNStepper object.

Parameters:

• stepper – a stepper object.

• content – a pointer to the stepper member data.

Returns:

A SUNErrCode indicating success or failure.

SUNErrCode SUNStepper_GetContent(SUNStepper stepper, void **content)

This function retrieves the member data (content) pointer from a SUNStepper object.

Parameters:

• stepper – a stepper object.

• content – a pointer to set to the stepper member data pointer.

Returns:

A SUNErrCode indicating success or failure.

13.1.1.5. Handling Warnings and Errors

An implementation of a SUNStepper may have a system of warning and error handling that cannot be encoded as a SUNErrCode which is the return type of all SUNStepper functions. Therefore, we provide the following function to get and set a separate flag associated with a stepper.

SUNErrCode SUNStepper_SetLastFlag(SUNStepper stepper, int last_flag)

This function sets a flag that can be used by SUNStepper implementations to indicate warnings or errors that occurred during an operation, e.g., SUNStepper_Evolve().

Parameters:

• stepper – the stepper object.

• last_flag – the flag value.

Returns:

A SUNErrCode indicating success or failure.

SUNErrCode SUNStepper_GetLastFlag(SUNStepper stepper, int *last_flag)

This function provides the last value of the flag used by the SUNStepper implementation to indicate warnings or errors that occurred during an operation, e.g., SUNStepper_Evolve().

Parameters:

• stepper – the stepper object.

• last_flag – A pointer to where the flag value will be written.

Returns:

A SUNErrCode indicating success or failure.

13.1.1.6. Setting Member Functions

The functions in this section are used to specify how each operation on a SUNStepper implementation is performed. Technically, all of these functions are optional to call; the functions that need to be attached are determined by the “consumer” of the SUNStepper.

SUNErrCode SUNStepper_SetEvolveFn(SUNStepper stepper, SUNStepperEvolveFn fn)

This function attaches a SUNStepperEvolveFn function to a SUNStepper object.

Parameters:

• stepper – a stepper object.

• fn – the SUNStepperEvolveFn function to attach.

Returns:

A SUNErrCode indicating success or failure.

SUNErrCode SUNStepper_SetOneStepFn(SUNStepper stepper, SUNStepperOneStepFn fn)

This function attaches a SUNStepperOneStepFn function to a SUNStepper object.

Parameters:

• stepper – a stepper object.

• fn – the SUNStepperOneStepFn function to attach.

Returns:

A SUNErrCode indicating success or failure.

SUNErrCode SUNStepper_SetFullRhsFn(SUNStepper stepper, SUNStepperFullRhsFn fn)

This function attaches a SUNStepperFullRhsFn function to a SUNStepper object.

Parameters:

• stepper – a stepper object.

• fn – the SUNStepperFullRhsFn function to attach.

Returns:

A SUNErrCode indicating success or failure.

SUNErrCode SUNStepper_SetReInitFn(SUNStepper stepper, SUNStepperResetFn fn)

This function attaches a SUNStepperReInitFn function to a SUNStepper object.

Parameters:

• stepper – a stepper object.

• fn – the SUNStepperReInitFn function to attach.

Returns:

A SUNErrCode indicating success or failure.

Added in version 7.3.0.

SUNErrCode SUNStepper_SetResetFn(SUNStepper stepper, SUNStepperResetFn fn)

This function attaches a SUNStepperResetFn function to a SUNStepper object.

Parameters:

• stepper – a stepper object.

• fn – the SUNStepperResetFn function to attach.

Returns:

A SUNErrCode indicating success or failure.

SUNErrCode SUNStepper_SetResetCheckpointIndexFn(SUNStepper stepper, SUNStepperResetCheckpointIndexFn fn)

This function attaches a SUNStepperResetCheckpointIndexFn function to a SUNStepper object.

Parameters:

• stepper – a stepper object.

• fn – the SUNStepperResetCheckpointIndexFn function to attach.

Returns:

A SUNErrCode indicating success or failure.

Added in version 7.3.0.

SUNErrCode SUNStepper_SetStopTimeFn(SUNStepper stepper, SUNStepperSetStopTimeFn fn)

This function attaches a SUNStepperSetStopTimeFn function to a SUNStepper object.

Parameters:

• stepper – a stepper object.

• fn – the SUNStepperSetStopTimeFn function to attach.

Returns:

A SUNErrCode indicating success or failure.

SUNErrCode SUNStepper_SetStepDirectionFn(SUNStepper stepper, SUNStepperSetStepDirectionFn fn)

This function attaches a SUNStepperSetStepDirectionFn function to a SUNStepper object.

Parameters:

• stepper – a stepper object.

• fn – the SUNStepperSetStepDirectionFn function to attach.

Returns:

A SUNErrCode indicating success or failure.

SUNErrCode SUNStepper_SetForcingFn(SUNStepper stepper, SUNStepperSetForcingFn fn)

This function attaches a SUNStepperSetForcingFn function to a SUNStepper object.

Parameters:

• stepper – a stepper object.

• fn – the SUNStepperSetForcingFn function to attach.

Returns:

A SUNErrCode indicating success or failure.

SUNErrCode SUNStepper_SetGetNumStepsFn(SUNStepper stepper, SUNStepperGetNumStepsFn fn)

This function attaches a SUNStepperGetNumStepsFn function to a SUNStepper object.

Parameters:

• stepper – a stepper object.

• fn – the SUNStepperGetNumStepsFn function to attach.

Returns:

A SUNErrCode indicating success or failure.

Added in version 7.3.0.

SUNErrCode SUNStepper_SetDestroyFn(SUNStepper stepper, SUNStepperDestroyFn fn)

This function attaches a SUNStepperDestroyFn function to a SUNStepper. The provided function is responsible for freeing any memory allocated for the SUNStepper content.

Parameters:

• stepper – a stepper object.

• fn – the SUNStepperDestroyFn function to attach.

Returns:

A SUNErrCode indicating success or failure.

13.1.2. Implementation Specific Methods

This section describes the virtual methods defined by the SUNStepper abstract base class.

typedef SUNErrCode (*SUNStepperEvolveFn)(SUNStepper stepper, sunrealtype tout, N_Vector vret, sunrealtype *tret)

This type represents a function with the signature of SUNStepper_Evolve().

typedef SUNErrCode (*SUNStepperOneStepFn)(SUNStepper stepper, sunrealtype tout, N_Vector vret, sunrealtype *tret)

This type represents a function with the signature of SUNStepper_OneStep().

typedef SUNErrCode (*SUNStepperFullRhsFn)(SUNStepper stepper, sunrealtype t, N_Vector v, N_Vector f, SUNFullRhsMode mode)

This type represents a function with the signature of SUNStepper_FullRhs().

typedef SUNErrCode (*SUNStepperResetFn)(SUNStepper stepper, sunrealtype tR, N_Vector vR)

This type represents a function with the signature of SUNStepper_Reset().

typedef SUNErrCode (*SUNStepperReInitFn)(SUNStepper stepper, sunrealtype tR, N_Vector vR)

This type represents a function with the signature of SUNStepper_ReInit().

Added in version 7.3.0.

typedef SUNErrCode (*SUNStepperResetCheckpointIndexFn)(SUNStepper stepper, suncountertype ckptIdxR)

This type represents a function with the signature of SUNStepper_ResetCheckpointIndex().

Added in version 7.3.0.

typedef SUNErrCode (*SUNStepperSetStopTimeFn)(SUNStepper stepper, sunrealtype tstop)

This type represents a function with the signature of SUNStepper_SetStopTime().

typedef SUNErrCode (*SUNStepperSetStepDirectionFn)(SUNStepper stepper, sunrealtype stepdir)

This type represents a function with the signature of SUNStepper_SetStepDirection().

typedef SUNErrCode (*SUNStepperSetForcingFn)(SUNStepper stepper, sunrealtype tshift, sunrealtype tscale, N_Vector *forcing, int nforcing)

This type represents a function with the signature of SUNStepper_SetForcing().

typedef SUNErrCode (*SUNStepperDestroyFn)(SUNStepper stepper)

This type represents a function with the signature similar to SUNStepper_Destroy() for freeing the content associated with a SUNStepper.

typedef SUNErrCode (*SUNStepperGetNumStepsFn)(SUNStepper stepper, suncountertype *nst)

This type represents a function with the signature of SUNStepper_GetNumSteps().

Added in version 7.3.0.

13.2. Implementing a SUNStepper

To create a SUNStepper implementation:

1. Define the stepper-specific content.

   This is typically a user-defined structure in C codes, a user-defined class or structure in C++ codes, or a user-defined module in Fortran codes. This content should hold any data necessary to perform the operations defined by the SUNStepper member functions.

2. Define implementations of the required member functions (see §13.1.2).

   These are typically user-defined functions in C, member functions of the user-defined structure or class in C++, or functions contained in the user-defined module in Fortran.

   Note that all member functions are passed the SUNStepper object and the stepper-specific content can, if necessary, be retrieved using SUNStepper_GetContent(). Stepper-specific warnings and errors can be recorded with SUNStepper_SetLastFlag().

3. In the user code, before creating the outer memory structure that uses the SUNStepper, e.g., with SplittingStepCreate() or ForcingStepCreate(), do the following:

   1. Create a SUNStepper object with SUNStepper_Create().

   2. Attach a pointer to the stepper content to the SUNStepper object with SUNStepper_SetContent() if necessary, e.g., when the content is a C structure.

   3. Attach the member function implementations using the functions described in §13.1.1.6.

4. Attach the SUNStepper object to the outer memory structure, e.g., with SplittingStepCreate() or ForcingStepCreate().