All SUNDIALS integrators (CVODE, CVODES, IDA) can be used in one of two main modes: normal and one step. Before defining the various relevant terms and describing the behavior and use of the integrators in each case, note that, internally, the SUNDIALS integrators work *independently* of this return mode. Indeed, regardless of the output mode, the method order and step size are chosen at any given time based solely on accuracy and solver performance criteria. The only difference is in the time at which control is passed back to the calling program. Optionally, the user can specify a time past which the integration is never to proceed (i.e.; no evaluations of any user-supplied functions will ever be made beyond this time). Note that, in this case, when approaching this barrier, the integration step size may be reduced to enforce this condition.
Although we will only use CVODE as an example, this note applies equally to CVODES and IDA. For clarity, we will assume that the integration proceeds towards larger times.
Definitions
The following names will be used in the sequel:
- tout
- The next time at which a computed solution is desired; tout is passed as an input to CVode.
- tret
- The time at which the solver returned control to the caling program; tret is an output from CVode.
- tstop
- The time past which the solution should not proceed; tstop is specified through CVodeSetStopTime.
- tn
- The time internally reached by the solver; tn is usually not "seen" by the user, but it can be obtained from CVodeGetCurrentTime.
The main solver function can therefore be called in one of the following modes (specified through the itask input argument to CVode):
- NORMAL
- The solver takes internal steps until it has reached or just passed tout. The solver then interpolates in order to return an approximate value of y(tout). In this case tret=tout.
- ONE_STEP
- The solver takes one internal step and returns the solution at the point reached by that step. In this case, tret=tn.
- NORMAL_TSTOP
- Same as NORMAL mode, except that the integration never proceeds past the value tstop. In this case, tret=tstop (or tret=tout if tout < tstop).
- ONE_STEP_TSTOP
- Same as ONE_STEP mode, except that the integration never proceeds past the value tstop. In this case, tret=tn (which may be equal to tstop).
Note that, in one step mode (ONE_STEP or ONE_STEP_TSTOP) the value tout is used only on the first call to CVode, to obtain the direction of integration (relative to the initial time specified in CVodeMalloc) and the rough time scale (used in estimating an initial step size).
Dense Output
In many situations, the solution may be desired at additional times between the tn values at which the solver computes the solution. Instead of enforcing a minimum step size — possible, but *inefficient* as this would effectively result in locally "over-solving" the ODE system (in that the step size may smaller than that required for the specified tolerances) — all SUNDIALS integrators provide dense output functions: CVodeGetDky in CVODE and CVODES, and IDAGetSolution in IDA. After a successful return from the solver function, the dense output functions return the interpolated solution at any time t such that tn - hu <= t <= tn, where hu is the last internal step size. In one step mode, the time t can therefore be anywhere between the last two return times from the main solver function.
Note that, unlike IDAGetsolution, the CVODE / CVODES function CVodeGetDky can also return the k-th derivative of the solution at time t, where k must be at most the current method order (obtainable from CVodeGetCurrentOrder). To obtain the interpolated solution, use k=0.
If the solution is desired at equally-spaced times (e.g., for plotting purposes), rather than calling the solver function in one step mode and then call the dense output function, it is more convenient (and may be more efficient) to call the solver function in normal mode, within a loop with successive tout values equal to the desired output times. Note that, if tout < tn (i.e., the solver has internally reached a time beyond the requasted tout), CVode will simply call the dense output function itself and then return.
Illustrations
For a typical sequence of internal steps tn, the above four modes are illustrated in the following figure. The black dots represent successive tn values, the green squares are requested output times tout, the red star is a stopping time tstop, and the blue arrows indicate actual values of the return times tret.
