Next: 6. Using CVODES for Up: User Documentation for CVODES Previous: 4. Code Organization Contents Index

Subsections

5. Using CVODES for IVP Solution

This chapter is concerned with the use of CVODES for the solution of initial value problems (IVPs). The following sections treat the header files and the layout of the user's main program, and provide descriptions of the CVODES user-callable functions and user-supplied functions.

This usage is essentially equivalent to using CVODE [19]. The listings of the sample programs in the companion document [17] may also be helpful. Those codes may be used as templates and are included in the CVODES package.

The user should be aware that not all linear solver modules are compatible with all NVECTOR implementations. For example, NVECTOR-PARALLEL is not compatible with the direct dense or direct band linear solvers since these linear solver modules need to form the complete system Jacobian. The following CVODES modules can only be used with NVECTOR-SERIAL: CVDENSE, CVBAND and CVBANDPRE. Also, the preconditioner module CVBBDPRE can only be used with NVECTOR-PARALLEL.

CVODES uses various constants for both input and output. These are defined as needed in this chapter, but for convenience are also listed separately in Chapter 11.

5.1 Access to libraries and header files

At this point, it is assumed that the installation of CVODES, following the procedure described in Chapter 2, has been completed successfully.

Regardless of where the user's application program resides, its associated compilation and load commands must make reference to the appropriate locations for the library and header files required by CVODES. The relevant library files are

libdir/libsundials_cvodes.lib,
libdir/libsundials_nvec*.lib (one or two files),

where the file extension .lib is typically .so for shared libraries and .a for static libraries. The relevant header files are located in the subdirectories

incdir/include
incdir/include/cvodes
incdir/include/sundials

The directories libdir and incdir are the install libray and include directories. For a default installation, these are builddir/lib and builddir/include, respectively, where builddir was defined in Chapter 2.

Note that an application cannot link to both the CVODE and CVODES libraries because both contain user-callable functions with the same names (to ensure that CVODES is backward compatible with CVODE). Therefore, applications that contain both IVP problems and IVPs with sensitivity analysis, should use CVODES.

5.2 Data Types

The sundials_types.h file contains the definition of the type realtype, which is used by the SUNDIALS solvers for all floating-point data. The type realtype can be float, double, or long double, with the default being double. The user can change the precision of the SUNDIALS solvers arithmetic at the configuration stage (see §2.1).

Additionally, based on the current precision, sundials_types.h defines BIG_REAL to be the largest value representable as a realtype, SMALL_REAL to be the smallest value representable as a realtype, and UNIT_ROUNDOFF to be the difference between 1.0 and the minimum realtype greater than 1.0.

Within SUNDIALS, real constants are set by way of a macro called RCONST. It is this macro that needs the ability to branch on the definition realtype. In ANSI C, a floating-point constant with no suffix is stored as a double. Placing the suffix ``F'' at the end of a floating point constant makes it a float, whereas using the suffix ``L'' makes it a long double. For example,

#define A 1.0
#define B 1.0F
#define C 1.0L

defines A to be a double constant equal to 1.0, B to be a float constant equal to 1.0, and C to be a long double constant equal to 1.0. The macro call RCONST(1.0) automatically expands to 1.0 if realtype is double, to 1.0F if realtype is float, or to 1.0L if realtype is long double. SUNDIALS uses the RCONST macro internally to declare all of its floating-point constants.

A user program which uses the type realtype and the RCONST macro to handle floating-point constants is precision-independent except for any calls to precision-specific standard math library functions. (Our example programs use both realtype and RCONST.) Users can, however, use the type double, float, or long double in their code (assuming the typedef for realtype matches this choice). Thus, a previously existing piece of ANSI C code can use SUNDIALS without modifying the code to use realtype, so long as the SUNDIALS libraries use the correct precision (for details see §2.1).

5.3 Header files

The calling program must include several header files so that various macros and data types can be used. The header file that is always required is:

cvodes.h, the main header file for CVODES, which defines the several types and various constants, and includes function prototypes.

Note that cvodes.h includes sundials_types.h, which defines the types realtype and booleantype and the constants FALSE and TRUE.

The calling program must also include an NVECTOR implementation header file (see §8 for details). For the two NVECTOR implementations that are included in the CVODES package, the corresponding header files are:

nvector_serial.h, which defines the serial implementation NVECTOR-SERIAL;
nvector_parallel.h, which defines the parallel (MPI) implementation, NVECTOR-PARALLEL.

Note that both these files in turn include the header file sundials_nvector.h which defines the abstract N_Vector data type.

Finally, if the user chooses Newton iteration for the solution of the nonlinear systems, then a linear solver module header file will be required. The header files corresponding to the various linear solvers availble for use with CVODES are:

cvodes_dense.h, which is used with the dense direct linear solver in the context of CVODES. This in turn includes a header file (sundials_dense.h) which defines the DenseMat type and corresponding accessor macros;
cvodes_band.h, which is used with the band direct linear solver in the context of CVODES. This in turn includes a header file (sundials_band.h) which defines the BandMat type and corresponding accessor macros;
cvodes_diag.h, which is used with the diagonal linear solver in the context of CVODES;
cvodes_spgmr.h, which is used with the Krylov solver SPGMR in the context of CVODES;
cvodes_spbcgs.h, which is used with the Krylov solver SPBCG in the context of CVODES;
cvodes_sptfqmr.h; which is used with the Krylov solver SPTFQMR in the context of CVODES;

The header files for the Krylov iterative solvers include cvodes_spils.h which defined common fuunctions and which in turn includes a header file (sundials_iterative.h) which enumerates the kind of preconditioning and for the choices for the Gram-Schmidt process for SPGMR.

Other headers may be needed, depending upon the choice of preconditioner, etc. In one of the examples in [18], preconditioning is done with a block-diagonal matrix. For this, the header sundials_smalldense.h is included.

5.4 A skeleton of the user's main program

The following is a skeleton of the user's main program (or calling program) for the integration of an ODE IVP. Some steps are independent of the NVECTOR implementation used; where this is not the case, usage specifications are given for the two implementations provided with CVODES: steps marked with [P] correspond to NVECTOR-PARALLEL, while steps marked with [S] correspond to NVECTOR-SERIAL.

[P] Initialize MPI
Call MPI_Init(&argc, &argv); to initialize MPI if used by the user's program. Here argc and argv are the command line argument counter and array received by main, respectively.
Set problem dimensions
[S] Set N, the problem size N.
[P] Set Nlocal, the local vector length (the sub-vector length for this process); N, the global vector length (the problem size N, and the sum of all the values of Nlocal); and the active set of processes.
Set vector of initial values
To set the vector y0 of initial values, use the appropriate functions defined by a particular NVECTOR implementation. If a realtype array ydata containing the initial values of y already exists, then make the call:
[S] y0 = N_VMake_Serial(N, ydata);
[P] y0 = N_VMake_Parallel(comm, Nlocal, N, ydata);
Otherwise, make the call:
[S] y0 = N_VNew_Serial(N);
[P] y0 = N_VNew_Parallel(comm, Nlocal, N);
and load initial values into the structure defined by:
[S] NV_DATA_S(y0)
[P] NV_DATA_P(y0)
Here comm is the MPI communicator, set in one of two ways: If a proper subset of active processes is to be used, comm must be set by suitable MPI calls. Otherwise, to specify that all processes are to be used, comm must be MPI_COMM_WORLD.
Create CVODES object
Call cvode_mem = CVodeCreate(lmm, iter); to create the CVODES memory block and to specify the solution method (linear multistep method and nonlinear solver iteration type). CVodeCreate returns a pointer to the CVODES memory structure. See §5.5.1 for details.
Allocate internal memory
Call CVodeMalloc(...); to provide required problem specifications, allocate internal memory for CVODES, and initialize CVODES. CVodeMalloc returns a flag, the value of which indicates either success or an illegal argument value. See §5.5.1 for details.
Set optional inputs
Call CVodeSet* functions to change any optional inputs that control the behavior of CVODES from their default values. See §5.5.5.1 for details.
Attach linear solver module
If Newton iteration is chosen, initialize the linear solver module with one of the following calls (for details see §5.5.3):
[S] ier = CVDense(...);
[S] ier = CVBand(...);
ier = CVDiag(...);
ier = CVSpgmr(...);
ier = CVSpbcg(...);
ier = CVSptfqmr(...);
Set linear solver optional inputs
Call CV*Set* functions from the selected linear solver module to change optional inputs specific to that linear solver. See §5.5.5 for details.
Specify rootfinding problem
Optionally, call CVodeRootInit to initialize a rootfinding problem to be solved during the integration of the ODE system. See §5.8.1 for details.
Advance solution in time
For each point at which output is desired, call ier = CVode(cvode_mem, tout, yout, &tret, itask); Set itask to specify the return mode. The vector y (which can be the same as the vector y0 above) will contain y(t). See §5.5.4 for details.
Get optional outputs
Call CV*Get* functions to obtain optional output. See §5.5.7 and §5.8.1 for details.
Deallocate memory for solution vector
Upon completion of the integration, deallocate memory for the vector y by calling the destructor function defined by the NVECTOR implementation:
[S] N_VDestroy_Serial(y);
[P] N_VDestroy_Parallel(y);
Free solver memory
Call CVodeFree(&cvode_mem); to free the memory allocated for CVODES.
[P] Finalize MPI
Call MPI_Finalize(); to terminate MPI.

5.5 User-callable functions for IVP solution

This section describes the CVODES functions that are called by the user to setup and then solve an IVP. Some of these are required. However, starting with §5.5.5, the functions listed involve optional inputs/outputs or restarting, and those paragraphs may be skipped for a casual use of CVODES. In any case, refer to §5.4 for the correct order of these calls. Calls related to rootfinding are described in §5.8.

5.5.1 CVODES initialization and deallocation functions

The following three functions must be called in the order listed. The last one is to be called only after the IVP solution is complete, as it frees the CVODES memory block created and allocated by the first two calls.

CVodeCreate

Call

cvode_mem = CVodeCreate(lmm, iter);

Description

The function CVodeCreate instantiates a CVODES solver object and specifies the solution method.

Arguments

lmm: (int) specifies the linear multistep method and may be one of two possible values: CV_ADAMS or CV_BDF.
iter: (int) specifies the type of nonlinear solver iteration and may be either CV_NEWTON or CV_FUNCTIONAL.

The recommended choices for (lmm, iter) are (CV_ADAMS, CV_FUNCTIONAL) for nonstiff problems and (CV_BDF, CV_NEWTON) for stiff problems.

Return value

If successful, CVodeCreate returns a pointer to the newly created CVODES memory block (of type void *). If an error occurred, CVodeCreate prints an error message to stderr and returns NULL.

Notes

CVodeMalloc

Call

flag = CVodeMalloc(cvode_mem, f, t0, y0, itol, reltol, abstol);

Description

The function CVodeMalloc provides required problem and solution specifications, allocates internal memory, and initializes CVODES.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block returned by CVodeCreate.
f: (CVRhsFn) is the C function which computes f in the ODE. This function has the form f(t, y, ydot, f_data) (for full details see §5.6.1).
t0: (realtype) is the initial value of t.
y0: (N_Vector) is the initial value of y.
itol: (int) is one of CV_SS, CV_SV, or CV_WF. Here itol = SS indicates scalar relative error tolerance and scalar absolute error tolerance, while itol = CV_SV indicates scalar relative error tolerance and vector absolute error tolerance. The latter choice is important when the absolute error tolerance needs to be different for each component of the ODE. If itol = CV_WF, the arguments reltol and abstol are ignored and the user is expected to provide a function to evaluate the error weight vector W, replacing (3.7). See CVodeSetEwtFn in §5.5.5.1.
reltol: (realtype) is the relative error tolerance.
abstol: (void *) is a pointer to the absolute error tolerance. If itol = CV_SS, abstol must be a pointer to a realtype variable. If itol = CV_SV, abstol must be an N_Vector variable.

Return value

The return value flag (of type int) will be one of the following:

CV_SUCCESS: The call to CVodeMalloc was successful.
CV_MEM_NULL: The CVODES memory block was not initialized through a previous call to CVodeCreate.
CV_MEM_FAIL: A memory allocation request has failed.
CV_ILL_INPUT: An input argument to CVodeMalloc has an illegal value.

Notes

See also §5.5.2 for advice on tolerances.

The tolerance values in reltol and abstol may be changed between calls to CVode (see CVodeSetTolerances in §5.5.5.1).

It is the user's responsibility to provide compatible itol and abstol arguments.

If an error occurred, CVodeMalloc also sends an error message to the error handler function.

CVodeFree
Call: CVodeFree(&cvode_mem);
Description: The function CVodeFree frees the memory allocated by a previous call to CVodeMalloc.
Arguments: The argument is the pointer to the CVODES memory block (of type void *).
Return value: The function CVodeFree has no return value.
Notes

5.5.2 Advice on choice and use of tolerances

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

(1) The scalar relative tolerance reltol is to be set to control relative errors. So reltol = 1.0E-4 means that errors are controlled to .01%. We do not recommend using reltol larger than 1.0E-3. On the other hand, reltol should not be so small that it is comparable to the unit roundoff of the machine arithmetic (generally around 1.0E-15).

(2) The absolute tolerances abstol (whether scalar or vector) need to be set to control absolute errors when any components of the solution vector y may be so small that pure relative error control is meaningless. For example, if y[i] starts at some nonzero value, but in time decays to zero, then pure relative error control on y[i] makes no sense (and is overly costly) after y[i] is below some noise level. Then abstol (if scalar) or abstol[i] (if a vector) needs to be set to that noise level. If the different components have different noise levels, then abstol should be a vector. See the example cvsdenx in the CVODE package, and the discussion of it in the CVODE Examples document [17]. In that problem, the three components vary betwen 0 and 1, and have different noise levels; hence the abstol vector. It is impossible to give any general advice on abstol values, because the appropriate noise levels are completely problem-dependent. The user or modeler hopefully has some idea as to what those noise levels are.

(3) Finally, it is important to pick all the tolerance values conservately, because they control the error committed on each individual time step. The final (global) errors are some sort of accumulation of those per-step errors. A good rule of thumb is to reduce the tolerances by a factor of .01 from the actual desired limits on errors. So if you want .01% accuracy (globally), a good choice is reltol = 1.0E-6. But in any case, it is a good idea to do a few experiments with the tolerances to see how the computed solution values vary as tolerances are reduced.

Advice on controlling unphysical negative values. In many applications, some components in the true solution are always positive or non-negative, though at times very small. In the numerical solution, however, small negative (hence unphysical) values can then occur. In most cases, these values are harmless, and simply need to be controlled, not eliminated. The following pieces of advice are relevant.

(1) The way to control the size of unwanted negative computed values is with tighter absolute tolerances. Again this requires some knowledge of the noise level of these components, which may or may not be different for different components. Some experimentation may be needed.

(2) If output plots or tables are being generated, and it is important to avoid having negative numbers appear there (for the sake of avoiding a long explanation of them, if nothing else), then eliminate them, but only in the context of the output medium. Then the internal values carried by the solver are unaffected. Remember that a small negative value in y returned by CVODES, with magnitude comparable to abstol or less, is equivalent to zero as far as the computation is concerned.

(3) The user's right-hand side routine f should never change a negative value in the solution vector y to a non-negative value, as a "solution" to this problem. This can cause instability. If the f routine cannot tolerate a zero or negative value (e.g. because there is a square root or log of it), then the offending value should be changed to zero or a tiny positive number in a temporary variable (not in the input y vector) for the purposes of computing f (t, y).

5.5.3 Linear solver specification functions

As previously explained, Newton iteration requires the solution of linear systems of the form (3.5). There are six CVODES linear solvers currently available for this task: CVDENSE, CVBAND, CVDIAG, CVSPGMR, CVSPBCG, and CVSPTFQMR. The first three are direct solvers and their names indicate the type of approximation used for the Jacobian J = $\partial$ f/ $\partial$ y; CVDENSE, CVBAND, and CVDIAG work with dense, banded, and diagonal approximations to J, respectively. The last three CVODES linear solvers -- CVSPGMR, CVSPBCG, and CVSPTFQMR -- are Krylov iterative solvers, which use scaled preconditioned GMRES, scaled preconditioned Bi-CGStab, and scaled preconditioned TFQMR, respectively. Together, they are refered to as CVSPILS (from scaled preconditioned iterative linear solvers).

With any of the Krylov methods, preconditioning can be done on the left only, on the right only, on both the left and the right, or not at all. For the specification of a preconditioner, see the iterative linear solver sections in §5.5.5 and §5.6.

If preconditioning is done, user-supplied functions define left and right preconditioner matrices P₁ and P₂ (either of which could be the identity matrix), such that the product P₁P₂ approximates the Newton matrix M = I - $\gamma$ J of (3.6).

To specify a CVODES linear solver, after the call to CVodeCreate but before any calls to CVode, the user's program must call one of the functions CVDense, CVBand, CVDiag, CVSpgmr, CVSpbcg, or CVSptfqmr, as documented below. The first argument passed to these functions is the CVODES memory pointer returned by CVodeCreate. A call to one of these functions links the main CVODES integrator to a linear solver and allows the user to specify parameters which are specific to a particular solver, such as the half-bandwidths in the CVBAND case. The use of each of the linear solvers involves certain constants and possibly some macros, that are likely to be needed in the user code. These are available in the corresponding header file associated with the linear solver, as specified below.

In each case except the diagonal approximation case CVDIAG, the linear solver module used by CVODES is actually built on top of a generic linear system solver, which may be of interest in itself. These generic solvers, denoted DENSE, BAND, SPGMR, SPBCG, and SPTFQMR, are described separately in Chapter 10.

CVDense

Call

flag = CVDense(cvode_mem, N);

Description

The function CVDense selects the CVDENSE linear solver.

The user's main program must include the cvodes_dense.h header file.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
N: (long int) problem dimension.

Return value

The return value flag (of type int) is one of:

CVDENSE_SUCCESS: The CVDENSE initialization was successful.
CVDENSE_MEM_NULL: The cvode_mem pointer is NULL.
CVDENSE_ILL_INPUT: The CVDENSE solver is not compatible with the current NVECTOR module.
CVDENSE_MEM_FAIL: A memory allocation request failed.

Notes

The CVDENSE linear solver may not be compatible with a particular implementation of the NVECTOR module. Of the two NVECTOR modules provided with SUNDIALS, only NVECTOR-SERIAL is compatible.

CVBand

Call

flag = CVBand(cvode_mem, N, mupper, mlower);

Description

The function CVBand selects the CVBAND linear solver.

The user's main program must include the cvodes_band.h header file.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
N: (long int) problem dimension.
mupper: (long int) upper half-bandwidth of the problem Jacobian (or of the approximation of it).
mlower: (long int) lower half-bandwidth of the problem Jacobian (or of the approximation of it).

Return value

The return value flag (of type int) is one of:

CVBAND_SUCCESS: The CVBAND initialization was successful.
CVBAND_MEM_NULL: The cvode_mem pointer is NULL.
CVBAND_ILL_INPUT: The CVBAND solver is not compatible with the current NVECTOR module, or one of the Jacobian half-bandwidths is outside of its valid range (0... N-1).
CVBAND_MEM_FAIL: A memory allocation request failed.

Notes

The CVBAND linear solver may not be compatible with a particular implementation of the NVECTOR module. Of the two NVECTOR modules provided with SUNDIALS, only NVECTOR-SERIAL is compatible. The half-bandwidths are to be set such that the nonzero locations (i, j) in the banded (approximate) Jacobian satisfy -mlower $\leq$ j - i $\leq$ mupper.

CVDiag

Call

flag = CVDiag(cvode_mem);

Description

The function CVDiag selects the CVDIAG linear solver.

The user's main function must include the cvodes_diag.h header file.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.

Return value

The return value flag (of type int) is one of:

CVDIAG_SUCCESS: The CVDIAG initialization was successful.
CVDIAG_MEM_NULL: The cvode_mem pointer is NULL.
CVDIAG_ILL_INPUT: The CVDIAG solver is not compatible with the current NVECTOR module.
CVDIAG_MEM_FAIL: A memory allocation request failed.

Notes

The CVDIAG solver is the simplest of all of the current CVODES linear solvers. The CVDIAG solver uses an approximate diagonal Jacobian formed by way of a difference quotient. The user does not have the option of supplying a function to compute an approximate diagonal Jacobian.

CVSpgmr

Call

flag = CVSpgmr(cvode_mem, pretype, maxl);

Description

The function CVSpgmr selects the CVSPGMR linear solver.

The user's main function must include the cvodes_spgmr.h header file.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
pretype: (int) specifies the preconditioning type and must be one of: PREC_NONE, PREC_LEFT, PREC_RIGHT, or PREC_BOTH.
maxl: (int) maximum dimension of the Krylov subspace to be used. Pass 0 to use the default value CVSPILS_MAXL = 5.

Return value

The return value flag (of type int) is one of

CVSPILS_SUCCESS: The CVSPGMR initialization was successful.
CVSPILS_MEM_NULL: The cvode_mem pointer is NULL.
CVSPILS_ILL_INPUT: The preconditioner type pretype is not valid.
CVSPILS_MEM_FAIL: A memory allocation request failed.

Notes

The CVSPGMR solver uses a scaled preconditioned GMRES iterative method to solve the linear system (3.5).

CVSpbcg

Call

flag = CVSpbcg(cvode_mem, pretype, maxl);

Description

The function CVSpbcg selects the CVSPBCG linear solver.

The user's main function must include the cvodes_spbcgs.h header file.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
pretype: (int) specifies the preconditioning type and must be one of: PREC_NONE, PREC_LEFT, PREC_RIGHT, or PREC_BOTH.
maxl: (int) maximum dimension of the Krylov subspace to be used. Pass 0 to use the default value CVSPILS_MAXL = 5.

Return value

The return value flag (of type int) is one of

CVSPILS_SUCCESS: The CVSPBCG initialization was successful.
CVSPILS_MEM_NULL: The cvode_mem pointer is NULL.
CVSPILS_ILL_INPUT: The preconditioner type pretype is not valid.
CVSPILS_MEM_FAIL: A memory allocation request failed.

Notes

The CVSPBCG solver uses a scaled preconditioned Bi-CGStab iterative method to solve the linear system (3.5).

CVSptfqmr

Call

flag = CVSptfqmr(cvode_mem, pretype, maxl);

Description

The function CVSptfqmr selects the CVSPTFQMR linear solver.

The user's main function must include the cvodes_sptfqmr.h header file.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
pretype: (int) specifies the preconditioning type and must be one of: PREC_NONE, PREC_LEFT, PREC_RIGHT, or PREC_BOTH.
maxl: (int) maximum dimension of the Krylov subspace to be used. Pass 0 to use the default value CVSPILS_MAXL = 5.

Return value

The return value flag (of type int) is one of

CVSPILS_SUCCESS: The CVSPTFQMR initialization was successful.
CVSPILS_MEM_NULL: The cvode_mem pointer is NULL.
CVSPILS_ILL_INPUT: The preconditioner type pretype is not valid.
CVSPILS_MEM_FAIL: A memory allocation request failed.

Notes

The CVSPTFQMR solver uses a scaled preconditioned TFQMR iterative method to solve the linear system (3.5).

5.5.4 CVODE solver function

This is the central step in the solution process - the call to perform the integration of the IVP.

CVode

Call

flag = CVode(cvode_mem, tout, yout, tret, itask);

Description

The function CVode integrates the ODE over an interval in t.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
tout: (realtype) the next time at which a computed solution is desired.
yout: (N_Vector) the computed solution vector.
tret: (realtype *) the time reached by the solver.
itask: (int) a flag indicating the job of the solver for the next user step. The CV_NORMAL option causes the solver to take internal steps until it has reached or just passed the user-specified tout parameter. The solver then interpolates in order to return an approximate value of y(tout). The CV_ONE_STEP option tells the solver to take just one internal step and then return the solution at the point reached by that step. The CV_NORMAL_TSTOP and CV_ONE_STEP_TSTOP modes are similar to CV_NORMAL and CV_ONE_STEP, respectively, except that the integration never proceeds past the value tstop (specified through the function CVodeSetStopTime).

Return value

On return, CVode returns a vector yout and a corresponding independent variable value t =*tret, such that yout is the computed value of y(t).

In CV_NORMAL mode (with no errors), *tret will be equal to tout and yout = y(tout).

The return value flag (of type int) will be one of the following:

CV_SUCCESS: CVode succeeded and no roots were found.
CV_TSTOP_RETURN: CVode succeeded by reaching the stopping point specified through the optional input function CVodeSetStopTime (see §5.5.5.1).
CV_ROOT_RETURN: CVode succeeded and found one or more roots. If nrtfn > 1, call CVodeGetRootInfo to see which g_i were found to have a root. See §5.8 for more information.
CV_MEM_NULL: The cvode_mem argument was NULL.
CV_NO_MALLOC: The CVODES memory was not allocated by a call to CVodeMalloc.
CV_ILL_INPUT: One of the inputs to CVode is illegal. This includes the situation where a root of one of the root functions was found both at a point t and also very near t. It also includes the situation where a component of the error weight vector becomes negative during internal time-stepping. The CV_ILL_INPUT flag will also be returned if the linear solver initialization function (called by the user after calling CVodeCreate) failed to set the linear solver-specific lsolve field in cvode_mem. In any case, the user should see the error message for details.
CV_TOO_CLOSE: The initial time t₀ and the final time t_out are too close to each other and the user did not specify an initial step size.
CV_TOO_MUCH_WORK: The solver took mxstep internal steps but still could not reach tout. The default value for mxstep is MXSTEP_DEFAULT = 500.
CV_TOO_MUCH_ACC: The solver could not satisfy the accuracy demanded by the user for some internal step.
CV_ERR_FAILURE: Either error test failures occurred too many times (MXNEF = 7) during one internal time step, or with | h| = h_min.
CV_CONV_FAILURE: Either convergence test failures occurred too many times (MXNCF = 10) during one internal time step, or with | h| = h_min.
CV_LINIT_FAIL: The linear solver's initialization function failed.
CV_LSETUP_FAIL: The linear solver's setup function failed in an unrecoverable manner.
CV_LSOLVE_FAIL: The linear solver's solve function failed in an unrecoverable manner.
CV_RHSFUNC_FAIL: The right-hand side function failed in an unrecoverable manner.
CV_FIRST_RHSFUNC_FAIL: The right-hand side function had a recoverable error at the first call.
CV_REPTD_RHSFUNC_ERR: Convergence tests occurred too many times due to repeated recoverable errors in the right-hand side function. The CV_REPTD_RHSFUNC_ERR will also be returned if the right-hand side function had repeated recoverable errors during the estimation of an initial step size.
CV_UNREC_RHSFUNC_ERR: The right-hand function had a recoverable error, but no recovery was possible. This failure mode is rare, as it can occur only if the right-hand side function fails recoverably after an error test failed while at order one.
CV_RTFUNC_FAIL: The rootfinding function failed.

Notes

The vector yout can occupy the same space as the y0 vector of initial conditions that was passed to CVodeMalloc.

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

All failure return values are negative and so the test ier < 0 will trap all CVode failures.

On any error return in which one or more internal steps were taken by CVode, 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 the previous CVode return.

5.5.5 Optional input functions

CVODES provides an extensive set of functions that can be used to change from their default values various optional input parameters that control the behavior of the CVODES solver. Table 5.1 lists all optional input functions in CVODES which are then described in detail in the remainder of this section, begining with those for the main CVODES solver and continuing with those for the linear solver modules. Note that the diagonal linear solver module has no optional inputs. For the most casual use of CVODES, the reader can skip to §5.6.

We note that, on error return, all of the optional input functions send an error message to the error handler function. We also note that all error return values are negative, so the test flag < 0 will catch all errors.

**Table 5.1:** Optional inputs for CVODES, CVDENSE, CVBAND, and CVSPILS
Optional input	Function name	Default
CVODE main solver
Error handler function	`CVodeSetErrHandlerFn`	internal fn.
Pointer to an error file	`CVodeSetErrFile`	`stderr`
Data for right-hand side function	`CVodeSetFdata`	`NULL`
Maximum order for BDF method	`CVodeSetMaxOrd`	5
Maximum order for Adams method	`CVodeSetMaxOrd`	12
Maximum no. of internal steps before t_out	`CVodeSetMaxNumSteps`	500
Maximum no. of warnings for t_n + h = t_n	`CVodeSetMaxHnilWarns`	10
Flag to activate stability limit detection	`CVodeSetStabLimDet`	`FALSE`
Initial step size	`CVodeSetInitStep`	estimated
Minimum absolute step size	`CVodeSetMinStep`	0.0
Maximum absolute step size	`CVodeSetMaxStep`	$\infty$
Value of t_stop	`CVodeSetStopTime`	undefined
Maximum no. of error test failures	`CVodeSetMaxErrTestFails`	7
Maximum no. of nonlinear iterations	`CVodeSetMaxNonlinIters`	3
Maximum no. of convergence failures	`CVodeSetMaxConvFails`	10
Coefficient in the nonlinear convergence test	`CVodeSetNonlinConvCoef`	0.1
Nonlinear iteration type	`CVodeSetIterType`	none
Integration tolerances	`CVodeSetTolerances`	none
Ewt compuation function	`CVodeSetEwtFn`	internal fn.
CVDENSE linear solver
Dense Jacobian function and data	`CVDenseSetJacFn`	internal DQ,
		NULL
CVBAND linear solver
Band Jacobian function and data	`CVBandSetJacFn`	internal DQ,
		NULL
CVSPILS linear solvers
Preconditioner functions and data	`CVSpilsSetPreconditioner`	all NULL
Jacobian-times-vector function and data	`CVSpilsSetJacTimesVecFn`	internal DQ,
		NULL
Preconditioning type	`CVSpilsSetPrecType`	none
Ratio between linear and nonlinear tolerances	`CVSpilsSetDelt`	0.05
Type of Gram-Schmidt orthogonalization^(a)	`CVSpilsSetGSType`	classical GS
Maximum Krylov subspace size^(b)	`CVSpilsSetMaxl`	5

^(a) Only for CVSPGMR
^(b) Only for CVSPBCG and CVSPTFQMR

5.5.5.1 Main solver optional input functions

The calls listed here can be executed in any order.
However, if CVodeSetErrHandlerFn or CVodeSetErrFile are to be called, that call should be first, in order to take effect for any later error message.

CVodeSetErrHandlerFn

Call

flag = CVodeSetErrHandlerFn(cvode_mem, ehfun, eh_data);

Description

The function CVodeSetErrHandlerFn specifies the optional user-defined function to be used in handling error messages.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
ehfun: (CVErrHandlerFn) is the C error handler function (see §5.6.2).
eh_data: (void *) pointer to user data passed to ehfun every time it is called.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The function ehfun and data pointer eh_data have been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.

Notes

The default internal error handler function directs error messages to the file specified by the file pointer errfp (see CVodeSetErrFile below).

Error messages indicating that the CVODES solver memory is NULL will always be directed to stderr.

CVodeSetErrFile

Call

flag = CVodeSetErrFile(cvode_mem, errfp);

Description

The function CVodeSetErrFile specifies a pointer to the file where all CVODES messages should be directed in case the default CVODES error handler function is used.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
errfp: (FILE *) pointer to output file.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The optional value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.

Notes

The default value for errfp is stderr.

Passing a value of NULL disables all future error message output (except for the case in which the CVODES memory pointer is NULL).

If CVodeSetErrFile is to be called, it should be called before any other optional input functions, in order to take effect for any later error message.

CVodeSetFdata

Call

flag = CVodeSetFdata(cvode_mem, f_data);

Description

The function CVodeSetFdata specifies the user-defined data block f_data to be passed to the user-supplied right-hand side function f, and attaches it to the main CVODES memory block.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
f_data: (void *) pointer to the user-defined data block.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The optional value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.

Notes

If f_data is not specified, a NULL pointer is passed to the f function.

CVodeSetMaxOrd

Call

flag = CVodeSetMaxOrder(cvode_mem, maxord);

Description

The function CVodeSetMaxOrder specifies the maximum order of the linear multistep method.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
maxord: (int) value of the maximum method order.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The optional value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.
CV_ILL_INPUT: The specified value maxord is negative or larger than its previous value.

Notes

The default value is ADAMS_Q_MAX = 12 for the Adams-Moulton method and BDF_Q_MAX = 5 for the BDF method. Since maxord affects the memory requirements for the internal CVODES memory block, its value cannot be increased past its previous value.

CVodeSetMaxNumSteps

Call

flag = CVodeSetMaxNumSteps(cvode_mem, mxsteps);

Description

The function CVodeSetMaxNumSteps specifies the maximum number of steps to be taken by the solver in its attempt to reach the next output time.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
mxsteps: (long int) maximum allowed number of steps.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The optional value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.
CV_ILL_INPUT: mxsteps is non-positive.

Notes

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

CVodeSetMaxHnilWarns

Call

flag = CVodeSetMaxHnilWarns(cvode_mem, mxhnil);

Description

The function CVodeSetMaxHnilWarns specifies the maximum number of messages issued by the solver warning that t + h = t on the next internal step.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
mxhnil: (int) maximum number of warning messages

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The optional value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.

Notes

The default value is 10. A negative value for mxhnil indicates that no warning messages should be issued.

CVodeSetStabLimDet

Call

flag = CVodeSetstabLimDet(cvode_mem, stldet);

Description

The function CVodeSetStabLimDet indicates if the BDF stability limit detection algorithm should be used. See §3.5 for further details.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
stldet: (booleantype) flag controlling stability limit detection (TRUE = on; FALSE = off).

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The optional value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.
CV_ILL_INPUT: The linear multistep method is not set to CV_BDF.

Notes

The default value is FALSE. If stldet = TRUE when BDF is used and the method order is greater than or equal to 3, then an internal function, CVsldet, is called to detect a possible stability limit. If such a limit is detected, then the order is reduced.

CVodeSetInitStep

Call

flag = CVodeSetInitStep(cvode_mem, hin);

Description

The function CVodeSetInitStep specifies the initial step size.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
hin: (realtype) value of the initial step size.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The optional value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.

Notes

By default, CVODES estimates the initial step size to be the solution h of the equation | 0.5h² $\ddot{y}$ |_WRMS = 1, where $\ddot{y}$ is an estimated second derivative of the solution at t0.

CVodeSetMinStep

Call

flag = CVodeSetMinStep(cvode_mem, hmin);

Description

The function CVodeSetMinStep specifies a lower bound on the magnitude of the step size.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
hmin: (realtype) minimum absolute value of the step size.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The optional value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.
CV_ILL_INPUT: Either hmin is nonpositive or it exceeds the maximum allowable step size.

Notes

The default value is 0.0.

CVodeSetMaxStep

Call

flag = CVodeSetMaxStep(cvode_mem, hmax);

Description

The function CVodeSetMaxStep specifies an upper bound on the magnitude of the step size.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
hmax: (realtype) maximum absolute value of the step size.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The optional value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.
CV_ILL_INPUT: Either hmax is nonpositive or it is smaller than the minimum allowable step size.

Notes

Pass hmax= 0 to obtain the default value $\infty$ .

CVodeSetStopTime

Call

flag = CVodeSetStopTime(cvode_mem, tstop);

Description

The function CVodeSetStopTime specifies the value of the independent variable t past which the solution is not to proceed.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
tstop: (realtype) value of the independent variable past which the solution should not proceed.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The optional value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.

Notes

The default value is $\infty$ .

CVodeSetMaxErrTestFails

Call

flag = CVodeSetMaxErrTestFails(cvode_mem, maxnef);

Description

The function CVodeSetMaxErrTestFails specifies the maximum number of error test failures permitted in attempting one step.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
maxnef: (int) maximum number of error test failures allowed on one step.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The optional value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.

Notes

The default value is 7.

CVodeSetMaxNonlinIters

Call

flag = CVodeSetMaxNonlinIters(cvode_mem, maxcor);

Description

The function CVodeSetMaxNonlinIters specifies the maximum number of nonlinear solver iterations permitted per step.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
maxcor: (int) maximum number of nonlinear solver iterations allowed per step.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The optional value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.

Notes

The default value is 3.

CVodeSetMaxConvFails

Call

flag = CVodeSetMaxConvFails(cvode_mem, maxncf);

Description

The function CVodeSetMaxConvFails specifies the maximum number of nonlinear solver convergence failures permitted during one step.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
maxncf: (int) maximum number of allowable nonlinear solver convergence failures per step.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The optional value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.

Notes

The default value is 10.

CVodeSetNonlinConvCoef

Call

flag = CVodeSetNonlinConvCoef(cvode_mem, nlscoef);

Description

The function CVodeSetNonlinConvCoef specifies the safety factor used in the nonlinear convergence test (see §3.1).

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
nlscoef: (realtype) coefficient in nonlinear convergence test.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The optional value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.

Notes

The default value is 0.1.

CVodeSetIterType

Call

flag = CVodeSetIterType(cvode_mem, iter);

Description

The function CVodeSetIterType resets the nonlinear solver iteration type to iter.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
iter: (int) specifies the type of nonlinear solver iteration and may be either CV_NEWTON or CV_FUNCTIONAL.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The optional value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.
CV_ILL_INPUT: The iter value passed is neither CV_NEWTON nor CV_FUNCTIONAL.

Notes

The nonlinear solver iteration type is initially specified in the call to CVodeCreate (see §5.5.1). This function call is needed only if iter is being changed from its value in the prior call to CVodeCreate.

CVodeSetTolerances

Call

flag = CVodeSetTolerances(cvode_mem, itol, reltol, abstol);

Description

The function CVodeSetTolerances resets the integration tolerances.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
itol: (int) is either CV_SS or CV_SV, where itol = CV_SS indicates scalar relative error tolerance and scalar absolute error tolerance, while itol=CV_SV indicates scalar relative error tolerance and vector absolute error tolerance. The latter choice is important when the absolute error tolerance needs to be different for each component of the ODE.
reltol: (realtype) the relative error tolerance.
abstol: (void *) is a pointer to the absolute error tolerance. If itol=CV_SS, abstol must be a pointer to a realtype variable. If itol=CV_SV, abstol must be an N_Vector variable.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The tolerances have been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.
CV_ILL_INPUT: An input argument has an illegal value.

Notes

The integration tolerances are initially specified in the call to CVodeMalloc (see §5.5.1). This function call is needed only if the tolerances are being changed from their values beween successiv calls to CVode.

It is the user's responsibility to provide compatible itol and abstol arguments.

It is illegal to call CVodeSetTolerances before a call to CVodeMalloc.

CVodeSetEwtFn

Call

flag = CVodeSetEwtFn(cvode_mem, efun, e_data);

Description

The function CVodeSetEwtFn specifies the user-defined function to be used in computing the error weight vector W, which is normally defined by Eq.(3.7).

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
efun: (CVEwtFn) is the C function which defines the ewt vector (see §5.6.3).
e_data: (void *) pointer to user data passed to efun every time it is called.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The function efun and data pointer e_data have been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.

Notes

This function can be called between successive calls to CVode.

If not needed, pass NULL for edata.

It is illegal to call CVodeSetEwtFn before a call to CVodeMalloc.

5.5.5.2 Dense linear solver

The CVDENSE solver needs a function to compute a dense approximation to the Jacobian matrix J(t, y). This function must be of type CVDenseJacFn. The user can supply his/her own dense Jacobian function, or use the default difference quotient function CVDenseDQJac that comes with the CVDENSE solver. To specify a user-supplied Jacobian function djac and associated user data jac_data, CVDENSE provides the function CVDenseSetJacFn. The CVDENSE solver passes the pointer jac_data to its dense Jacobian function. This allows the user to create an arbitrary structure with relevant problem data and access it during the execution of the user-supplied Jacobian function, without using global data in the program. The pointer jac_data may be identical to f_data, if the latter was specified through CVodeSetFdata.

CVDenseSetJacFn

Call

flag = CVDenseSetJacFn(cvode_mem, djac, jac_data);

Description

The function CVDenseSetJacFn specifies the dense Jacobian approximation function to be used and the pointer to user data.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
djac: (CVDenseJacFn) user-defined dense Jacobian approximation function.
jac_data: (void *) pointer to the user-defined data structure.

Return value

The return value flag (of type int) is one of

CVDENSE_SUCCESS: The optional value has been successfully set.
CVDENSE_MEM_NULL: The cvode_mem pointer is NULL.
CVDENSE_LMEM_NULL: The CVDENSE linear solver has not been initialized.

Notes

By default, CVDENSE uses the difference quotient function CVDenseDQJac. If NULL is passed to djac, this default function is used.

The function type CVDenseJacFn is described in §5.6.4.

5.5.5.3 Band linear solver

The CVBAND solver needs a function to compute a banded approximation to the Jacobian matrix J(t, y). This function must be of type CVBandJacFn. The user can supply his/her own banded Jacobian approximation function, or use the default difference quotient function CVBandDQJac that comes with the CVBAND solver. To specify a user-supplied Jacobian function bjac and associated user data jac_data, CVBAND provides the function CVBandSetJacFn. The CVBAND solver passes the pointer jac_data to its banded Jacobian approximation function. This allows the user to create an arbitrary structure with relevant problem data and access it during the execution of the user-supplied Jacobian function, without using global data in the program. The pointer jac_data may be identical to f_data, if the latter was specified through CVodeSetFdata.

CVBandSetJacFn

Call

flag = CVBandSetJacFn(cvode_mem, bjac, jac_data);

Description

The function CVBandSetJacFn specifies the banded Jacobian approximation function to be used and the pointer to user data.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
bjac: (CVBandJacFn) user-defined banded Jacobian approximation function.
jac_data: (void *) pointer to the user-defined data structure.

Return value

The return value flag (of type int) is one of

CVBAND_SUCCESS: The optional value has been successfully set.
CVBAND_MEM_NULL: The cvode_mem pointer is NULL.
CVBAND_LMEM_NULL: The CVBAND linear solver has not been initialized.

Notes

By default, CVBAND uses the difference quotient function CVBandDQJac. If NULL is passed to bjac, this default function is used.

The function type CVBandJacFn is described in §5.6.5.

5.5.5.4 SPILS linear solver

If any preconditioning is to be done within one of the CVSPILS linear solvers, then the user must supply a preconditioner solve function psolve and specify its name in a call to CVSpilsSetPreconditioner. The evaluation and preprocessing of any Jacobian-related data needed by the user's preconditioner solve function is done in the optional user-supplied function psetup. Both of these functions are fully specified in §5.6. If used, the psetup function should also be specified in the call to CVSpilsSetPreconditioner. Optionally, a CVSPILS solver passes the pointer p_data received through CVSpilsSetPreconditioner to the preconditioner psetup and psolve functions. This allows the user to create an arbitrary structure with relevant problem data and access it during the execution of the user-supplied preconditioner functions without using global data in the program. The pointer p_data may be identical to f_data, if the latter was specified through CVodeSetFdata.

Ther CVSPILS solvers require a function to compute an approximation to the product between the Jacobian matrix J(t, y) and a vector v. The user can supply his/her own Jacobian-times-vector approximation function, or use the difference quotient function CVSpilsDQJtimes that comes with the CVSPILS solvers. A user-defined Jacobian-vector function must be of type CVSpilsJacTimesVecFn and can be specified through a call to CVSpilsSetJacTimesVecFn (see §5.6.6 for specification details). As with the preconditioner user data structure p_data, the user can also specify, in the call to CVSpilsSetJacTimesVecFn, a pointer to a user-defined data structure, jac_data, which the CVSPILS solver passes to the Jacobian-times-vector function jtimes each time it is called. The pointer jac_data may be identical to p_data and/or f_data.

CVSpilsSetPreconditioner

Call

flag = CVSpilsSetPreconditioner(cvode_mem, psetup, psolve, p_data);

Description

The function CVSpilsSetPreconditioner specifies the preconditioner setup and solve functions and the pointer to user data.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
psetup: (CVSpilsPrecSetupFn) user-defined preconditioner setup function.
psolve: (CVSpilsPrecSolveFn) user-defined preconditioner solve function.
p_data: (void *) pointer to the user-defined data structure.

Return value

The return value flag (of type int) is one of

CVSPILS_SUCCESS: The optional value has been successfully set.
CVSPILS_MEM_NULL: The cvode_mem pointer is NULL.
CVSPILS_LMEM_NULL: The CVSPILS linear solver has not been initialized.

Notes

The function type CVSpilsPrecSolveFn is described in §5.6.7. The function type CVSpilsPrecSetupFn is described in §5.6.8.

CVSpilsSetJacTimesVecFn

Call

flag = CVSpilsSetJacTimesVecFn(cvode_mem, jtimes, jac_data);

Description

The function CVSpilsSetJacTimesFn specifies the Jacobian-vector function to be used and the pointer to user data.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
jtimes: (CVSpilsJacTimesVecFn) user-defined Jacobian-vector product function.
jac_data: (void *) pointer to the user-defined data structure.

Return value

The return value flag (of type int) is one of

CVSPILS_SUCCESS: The optional value has been successfully set.
CVSPILS_MEM_NULL: The cvode_mem pointer is NULL.
CVSPILS_LMEM_NULL: The CVSPILS linear solver has not been initialized.

Notes

By default, the CVSPILS linear solvers use an internal difference quotient function CVSpilsDQJtimes. If NULL is passed to jtimes, this default function is used.

The function type CVSpilsJacTimesVecFn is described in §5.6.6.

CVSpilsSetPrecType

Call

flag = CVSpilsSetPrecType(cvode_mem, pretype);

Description

The function CVSpilsSetPrecType resets the type of preconditioning to be used.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
pretype: (int) specifies the type of preconditioning and must be one of: PREC_NONE, PREC_LEFT, PREC_RIGHT, or PREC_BOTH.

Return value

The return value flag (of type int) is one of

CVSPILS_SUCCESS: The optional value has been successfully set.
CVSPILS_MEM_NULL: The cvode_mem pointer is NULL.
CVSPILS_LMEM_NULL: The CVSPILS linear solver has not been initialized.
CVSPILS_ILL_INPUT: The preconditioner type pretype is not valid.

Notes

The preconditioning type is initially set in the call to the linear solver's specification function (see §5.5.3). This function call is needed only if pretype is being changed from its original value.

CVSpilsSetGSType

Call

flag = CVSpilsSetGSType(cvode_mem, gstype);

Description

The function CVSpilsSetGSType specifies the Gram-Schmidt orthogonalization to be used with the CVSPGMR solver (one of the enumeration constants MODIFIED_GS or CLASSICAL_GS). These correspond to using modified Gram-Schmidt and classical Gram-Schmidt, respectively.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
gstype: (int) type of Gram-Schmidt orthogonalization.

Return value

The return value flag (of type int) is one of

CVSPILS_SUCCESS: The optional value has been successfully set.
CVSPILS_MEM_NULL: The cvode_mem pointer is NULL.
CVSPILS_LMEM_NULL: The CVSPILS linear solver has not been initialized.
CVSPILS_ILL_INPUT: The Gram-Schmidt orthogonalization type gstype is not valid.

Notes

The default value is MODIFIED_GS.

This option is available only for the CVSPGMR linear solver.

CVSpilsSetDelt

Call

flag = CVSpilsSetDelt(cvode_mem, delt);

Description

The function CVSpilsSetDelt specifies the factor by which the Krylov linear solver's convergence test constant is reduced from the Newton iteration test constant.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
delt: (realtype)

Return value

The return value flag (of type int) is one of

CVSPILS_SUCCESS: The optional value has been successfully set.
CVSPILS_MEM_NULL: The cvode_mem pointer is NULL.
CVSPILS_LMEM_NULL: The CVSPILS linear solver has not been initialized.
CVSPILS_ILL_INPUT: The factor delt is negative.

Notes

The default value is 0.05.

Passing a value delt= 0.0 also indicates using the default value.

CVSpilsSetMaxl

Call

flag = CVSpilsSetMaxl(cv_mem, maxl);

Description

The function CVSpilsSetMaxl resets maximum Krylov subspace dimension for the Bi-CGStab or TFQMR methods.

Arguments

cv_mem: (void *) pointer to the CVODES memory block.
maxl: (int) maximum dimension of the Krylov subspace.

Return value

The return value flag (of type int) is one of

CVSPILS_SUCCESS: The optional value has been successfuly set.
CVSPILS_MEM_NULL: The cv_mem pointer is NULL.
CVSPILS_LMEM_NULL: The CVSPILS linear solver has not been initialized.

Notes

The maximum subspace dimension is initially specified in the call to the linear solver specification function (see §5.5.3). This function call is needed only if maxl is being changed from its previous value.

This option is available only for the CVSPBCG and CVSPTFQMR linear solvers.

5.5.6 Interpolated output function

An optional function CVodeGetDky is available to obtain additional output values. This function should only be called after a successful return from CVode as it provides interpolated values either of y or of its derivatives (up to the current order of the integration method) interpolated to any value of t in the last internal step taken by CVODES.

The call to the CVodeGetDky function has the following form:

CVodeGetDky

Call

flag = CVodeGetDky(cvode_mem, t, k, dky);

Description

The function CVodeGetDky computes the k-th derivative of the function y at time t, i.e. d^(k)y/dt^(k)(t), where t_n - h_u $\le$ t $\le$ t_n, t_n denotes the current internal time reached, and h_u is the last internal step size successfully used by the solver. The user may request k = 0, 1,..., q_u, where q_u is the current order.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
t: (realtype) the value of the independent variable at which the derivative is to be evaluated.
k: (int) the derivative order requested.
dky: (N_Vector) vector containing the derivative. This vector must be allocated by the user.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: CVodeGetDky succeeded.
CV_BAD_K: k is not in the range 0, 1,..., q_u.
CV_BAD_T: t is not in the interval [t_n - h_u, t_n].
CV_BAD_DKY: The dky argument was NULL.
CV_MEM_NULL: The cvode_mem argument was NULL.

Notes

It is only legal to call the function CVodeGetDky after a successful return from CVode. See CVodeGetCurrentTime, CVodeGetLastOrder, and CVodeGetLastStep in the next section for access to t_n, q_u, and h_u, respectively.

5.5.7 Optional output functions

CVODES provides an extensive set of functions that can be used to obtain solver performance information. Table 5.2 lists all optional output functions in CVODES, which are then described in detail in the remainder of this section, begining with those for the main CVODES solver and continuing with those for the linear solver modules. Where the name of an output from a linear solver module would otherwise conflict with the name of an optional output from the main solver, a suffix LS (for Linear Solver) has been added here (e.g. lenrwLS).

**Table 5.2:** Optional outputs from CVODES, CVDENSE, CVBAND, CVDIAG, and CVSPILS
Optional output	Function name
CVODES main solver
Size of CVODES real and integer workspaces	`CVodeGetWorkSpace`
Cumulative number of internal steps	`CVodeGetNumSteps`
No. of calls to r.h.s. function	`CVodeGetNumRhsEvals`
No. of calls to linear solver setup function	`CVodeGetNumLinSolvSetups`
No. of local error test failures that have occurred	`CVodeGetNumErrTestFails`
Order used during the last step	`CVodeGetLastOrder`
Order to be attempted on the next step	`CVodeGetCurrentOrder`
No. of order reductions due to stability limit detection	`CVodeGetNumStabLimOrderReds`
Actual initial step size used	`CVodeGetActualInitStep`
Step size used for the last step	`CVodeGetLastStep`
Step size to be attempted on the next step	`CVodeGetCurrentStep`
Current internal time reached by the solver	`CVodeGetCurrentTime`
Suggested factor for tolerance scaling	`CVodeGetTolScaleFactor`
Error weight vector for state variables	`CVodeGetErrWeights`
Estimated local error vector	`CVodeGetEstLocalErrors`
No. of nonlinear solver iterations	`CVodeGetNumNonlinSolvIters`
No. of nonlinear convergence failures	`CVodeGetNumNonlinSolvConvFails`
All CVODES integrator statistics	`CVodeGetIntegratorStats`
CVODES nonlinear solver statistics	`CVodeGetNonlinSolvStats`
Array showing roots found	`CvodeGetRootInfo`
No. of calls to user root function	`CVodeGetNumGEvals`
Name of constant associated with a return flag	`CVodeGetReturnFlagName`
CVDENSE linear solver
Size of CVDENSE real and integer workspaces	`CVDenseGetWorkSpace`
No. of Jacobian evaluations	`CVDenseGetNumJacEvals`
No. of r.h.s. calls for finite diff. Jacobian evals.	`CVDenseGetNumRhsEvals`
Last return from a CVDENSE function	`CVDenseGetLastFlag`
Name of constant associated with a return flag	`CVDenseGetReturnFlagName`
CVBAND linear solver
Size of CVBAND real and integer workspaces	`CVBandGetWorkSpace`
No. of Jacobian evaluations	`CVBandGetNumJacEvals`
No. of r.h.s. calls for finite diff. Jacobian evals.	`CVBandGetNumRhsEvals`
Last return from a CVBAND function	`CVBandGetLastFlag`
Name of constant associated with a return flag	`CVBandGetReturnFlagName`
CVDIAG linear solver
Size of CVDIAG real and integer workspaces	`CVDiagGetWorkSpace`
No. of r.h.s. calls for finite diff. Jacobian evals.	`CVDiagGetNumRhsEvals`
Last return from a CVDIAG function	`CVDiagGetLastFlag`
Name of constant associated with a return flag	`CVDiagGetReturnFlagName`
CVSPILS linear solvers
Size of real and integer workspaces	`CVSpilsGetWorkSpace`
No. of linear iterations	`CVSpilsGetNumLinIters`
No. of linear convergence failures	`CVSpilsGetNumConvFails`
No. of preconditioner evaluations	`CVSpilsGetNumPrecEvals`
No. of preconditioner solves	`CVSpilsGetNumPrecSolves`
No. of Jacobian-vector product evaluations	`CVSpilsGetNumJtimesEvals`
No. of r.h.s. calls for finite diff. Jacobian-vector evals.	`CVSpilsGetNumRhsEvals`
Last return from a linear solver function	`CVSpilsGetLastFlag`
Name of constant associated with a return flag	`CVSpilsGetReturnFlagName`

5.5.7.1 Main solver optional output functions

CVODES provides several user-callable functions that can be used to obtain different quantities that may be of interest to the user, such as solver workspace requirements, solver performance statistics, as well as additional data from the CVODES memory block (a suggested tolerance scaling factor, the error weight vector, and the vector of estimated local errors). Functions are also provided to extract statistics related to the performance of the CVODES nonlinear solver used. As a convenience, additional information extraction functions provide the optional outputs in groups. These optional output functions are described next.

CVodeGetWorkSpace

Call

flag = CVodeGetWorkSpace(cvode_mem, &lenrw, &leniw);

Description

The function CVodeGetWorkSpace returns the CVODES real and integer workspace sizes.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
lenrw: (long int) the number of realtype values in the CVODES workspace.
leniw: (long int) the number of integer values in the CVODES workspace.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The optional output values have been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.

Notes

In terms of the problem size N, the maximum method order maxord, and the number nrtfn of root functions (see §5.8), the actual size of the real workspace, in realtype words, is given by the following:

base value: lenrw = 96 + (maxord+5 )*N_r + 3*nrtfn;
if itol = CV_SV: lenrw = lenrw + N_r;

where N_r is the number of real words in one N_Vector ( $\approx$ N).

The size of the integer workspace (without distinction between int and long int words) is given by:

base value: leniw = 40 + (maxord+5 )*N_i + nrtfn;
if itol = CV_SV: leniw = leniw + N_i;

where N_i is the number of integer words in one N_Vector (= 1 for NVECTOR-SERIAL and 2*npes for NVECTOR-PARALLEL and npes processors).

For the default value of maxord, with no rootfinding, and with itol $\neq$ CV_SV, these lengths are given roughly by:

For the Adams method: lenrw = 96 + 17N and leniw = 57
For the BDF method: lenrw = 96 + 10N and leniw = 50

Note that additional memory is allocated if quadratures and/or forward sensitivity integration is enabled. See §5.7.1 and §6.2.1 for more details.

CVodeGetNumSteps

Call

flag = CVodeGetNumSteps(cvode_mem, &nsteps);

Description

The function CVodeGetNumSteps returns the cumulative number of internal steps taken by the solver (total so far).

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
nsteps: (long int) number of steps taken by CVODES.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The optional output value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.

Notes

CVodeGetNumRhsEvals

Call

flag = CVodeGetNumRhsEvals(cvode_mem, &nfevals);

Description

The function CVodeGetNumRhsEvals returns the number of calls to the user's right-hand side function.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
nfevals: (long int) number of calls to the user's f function.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The optional output value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.

Notes

The nfevals value returned by CVodeGetNumRhsEvals does not account for calls made to f by a linear solver or preconditioner module.

CVodeGetNumLinSolvSetups

Call

flag = CVodeGetNumLinSolvSetups(cvode_mem, &nlinsetups);

Description

The function CVodeGetNumLinSolvSetups returns the number of calls made to the linear solver's setup function.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
nlinsetups: (long int) number of calls made to the linear solver setup function.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The optional output value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.

Notes

CVodeGetNumErrTestFails

Call

flag = CVodeGetNumErrTestFails(cvode_mem, &netfails);

Description

The function CVodeGetNumErrTestFails returns the number of local error test failures that have occurred.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
netfails: (long int) number of error test failures.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The optional output value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.

Notes

CVodeGetLastOrder

Call

flag = CVodeGetLastOrder(cvode_mem, &qlast);

Description

The function CVodeGetLastOrder returns the integration method order used during the last internal step.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
qlast: (int) method order used on the last internal step.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The optional output value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.

Notes

CVodeGetCurrentOrder

Call

flag = CVodeGetCurrentOrder(cvode_mem, &qcur);

Description

The function CVodeGetCurrentOrder returns the integration method order to be used on the next internal step.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
qcur: (int) method order to be used on the next internal step.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The optional output value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.

Notes

CVodeGetLastStep

Call

flag = CVodeGetLastStep(cvode_mem, &hlast);

Description

The function CVodeGetLastStep returns the integration step size taken on the last internal step.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
hlast: (realtype) step size taken on the last internal step.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The optional output value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.

Notes

CVodeGetCurrentStep

Call

flag = CVodeGetCurrentStep(cvode_mem, &hcur);

Description

The function CVodeGetCurrentStep returns the integration step size to be attempted on the next internal step.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
hcur: (realtype) step size to be attempted on the next internal step.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The optional output value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.

Notes

CVodeGetActualInitStep

Call

flag = CVodeGetActualInitStep(cvode_mem, &hinused);

Description

The function CVodeGetActualInitStep returns the value of the integration step size used on the first step.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
hinused: (realtype) actual value of initial step size.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The optional output value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.

Notes

Even if the value of the initial integration step size was specified by the user through a call to CVodeSetInitStep, this value might have been changed by CVODES to ensure that the step size is within the prescribed bounds ( h_min $\le$ h₀ $\le$ h_max), or to satisfy the local error test condition.

CVodeGetCurrentTime

Call

flag = CVodeGetCurrentTime(cvode_mem, &tcur);

Description

The function CVodeGetCurrentTime returns the current internal time reached by the solver.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
tcur: (realtype) current internal time reached.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The optional output value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.

Notes

CVodeGetNumStabLimOrderReds

Call

flag = CVodeGetNumStabLimOrderReds(cvode_mem, &nslred);

Description

The function CVodeGetNumStabLimOrderReds returns the number of order reductions dictated by the BDF stability limit detection algorithm (see §3.5).

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
nslred: (long int) number of order reductions due to stability limit detection.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The optional output value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.

Notes

If the stability limit detection algorithm was not initialized through a call to CVodeSetStabLimDet, then nslred=0.

CVodeGetTolScaleFactor

Call

flag = CVodeGetTolScaleFactor(cvode_mem, &tolsfac);

Description

The function CVodeGetTolScaleFactor 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

cvode_mem: (void *) pointer to the CVODES memory block.
tolsfac: (realtype) suggested scaling factor for user-supplied tolerances.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The optional output value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.

Notes

CVodeGetErrWeights

Call

flag = CVodeGetErrWeights(cvode_mem, eweight);

Description

The function CVodeGetErrWeights returns the solution error weights at the current time. These are the reciprocals of the W_i given by (3.7).

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
eweight: (N_Vector) solution error weights at the current time.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The optional output value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.

Notes

The user must allocate memory for eweight.

CVodeGetEstLocalErrors

Call

flag = CVodeGetEstLocalErrors(cvode_mem, ele);

Description

The function CVodeGetEstLocalErrors returns the vector of estimated local errors.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
ele: (N_Vector) estimated local errors.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The optional output value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.

Notes

The user must allocate memory for ele.

The ele vector, togther with the eweight vector from CVodeGetErrWeights, 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 RMS norm of a vector whose components are the products of the components of the 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].

CVodeGetIntegratorStats

Call

	`flag = CVodeGetIntegratorStats(`		`cvode_mem, &nsteps, &nfevals,`
			`&nlinsetups, &netfails, &qlast, &qcur,`
			`&hinused, &hlast, &hcur, &tcur);`

Description

The function CVodeGetIntegratorStats returns the CVODES integrator statistics as a group.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
nsteps: (long int) number of steps taken by CVODES.
nfevals: (long int) number of calls to the user's f function.
nlinsetups: (long int) number of calls made to the linear solver setup function.
netfails: (long int) number of error test failures.
qlast: (int) method order used on the last internal step.
qcur: (int) method order to be used on the next internal step.
hinused: (realtype) actual value of initial step size.
hlast: (realtype) step size taken on the last internal step.
hcur: (realtype) step size to be attempted on the next internal step.
tcur: (realtype) current internal time reached.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: the optional output values have been successfully set.
CV_MEM_NULL: the cvode_mem pointer is NULL.

Notes

CVodeGetNumNonlinSolvIters

Call

flag = CVodeGetNumNonlinSolvIters(cvode_mem, &nniters);

Description

The function CVodeGetNumNonlinSolvIters returns the number of nonlinear (functional or Newton) iterations performed.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
nniters: (long int) number of nonlinear iterations performed.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The optional output values have been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.

Notes

CVodeGetNumNonlinSolvConvFails

Call

flag = CVodeGetNumNonlinSolvConvFails(cvode_mem, &nncfails);

Description

The function CVodeGetNumNonlinSolvConvFails returns the number of nonlinear convergence failures that have occurred.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
nncfails: (long int) number of nonlinear convergence failures.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The optional output value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.

Notes

CVodeGetNonlinSolvStats

Call

flag = CVodeGetNonlinSolvStats(cvode_mem, &nniters, &nncfails);

Description

The function CVodeGetNonlinSolvStats returns the CVODES nonlinear solver statistics as a group.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
nniters: (long int) number of nonlinear iterations performed.
nncfails: (long int) number of nonlinear convergence failures.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The optional output value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.

Notes

CVodeGetReturnFlagName
Call: name = CVodeGetReturnFlagName(flag);
Description: The function CVodeGetReturnFlagName returns the name of the CVODE constant corresponding to flag.
Arguments: The only argument, of type int is a return flag from a CVODE function.
Return value: The return value is a string containing the name of the corresponding constant.
Notes

5.5.7.2 Dense linear solver

The following optional outputs are available from the CVDENSE module: workspace requirements, number of calls to the Jacobian routine, number of calls to the right-hand side routine for finite-difference Jacobian approximation, and last return value from a CVDENSE function.

CVDenseGetWorkSpace

Call

flag = CVDenseGetWorkSpace(cvode_mem, &lenrwLS, &leniwLS);

Description

The function CVDenseGetWorkSpace returns the CVDENSE real and integer workspace sizes.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
lenrwLS: (long int) the number of realtype values in the CVDENSE workspace.
leniwLS: (long int) the number of integer values in the CVDENSE workspace.

Return value

The return value flag (of type int) is one of

CVDENSE_SUCCESS: The optional output values have been successfully set.
CVDENSE_MEM_NULL: The cvode_mem pointer is NULL.
CVDENSE_LMEM_NULL: The CVDENSE linear solver has not been initialized.

Notes

In terms of the problem size N, the actual size of the real workspace is 2N² realtype words, and the actual size of the integer workspace is N integer words.

CVDenseGetNumJacEvals

Call

flag = CVDenseGetNumJacEvals(cvode_mem, &njevals);

Description

The function CVDenseGetNumJacEvals returns the number of calls made to the dense Jacobian approximation function.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
njevals: (long int) the number of calls to the Jacobian function.

Return value

The return value flag (of type int) is one of

CVDENSE_SUCCESS: The optional output value has been successfully set.
CVDENSE_MEM_NULL: The cvode_mem pointer is NULL.
CVDENSE_LMEM_NULL: The CVDENSE linear solver has not been initialized.

Notes

CVDenseGetNumRhsEvals

Call

flag = CVDenseGetNumRhsEvals(cvode_mem, &nfevalsLS);

Description

The function CVDenseGetNumRhsEvals returns the number of calls made to the user-supplied right-hand side function due to the finite difference dense Jacobian approximation.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
nfevalsLS: (long int) the number of calls made to the user-supplied right-hand side function.

Return value

The return value flag (of type int) is one of

CVDENSE_SUCCESS: The optional output value has been successfully set.
CVDENSE_MEM_NULL: The cvode_mem pointer is NULL.
CVDENSE_LMEM_NULL: The CVDENSE linear solver has not been initialized.

Notes

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

CVDenseGetLastFlag

Call

flag = CVDenseGetLastFlag(cvode_mem, &lsflag);

Description

The function CVDenseGetLastFlag returns the last return value from a CVDENSE routine.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
lsflag: (int) the value of the last return flag from a CVDENSE function.

Return value

The return value flag (of type int) is one of

CVDENSE_SUCCESS: The optional output value has been successfully set.
CVDENSE_MEM_NULL: The cvode_mem pointer is NULL.
CVDENSE_LMEM_NULL: The CVDENSE linear solver has not been initialized.

Notes

If the CVDENSE setup function failed (CVode returned CV_LSETUP_FAIL), then the value of lsflag corresponds to the column index (numbered from one) of a diagonal element with value zero that was encountered during the LU factorization of the dense Jacobian matrix.

CVDenseGetReturnFlagName
Call: name = CVDenseGetReturnFlagName(flag);
Description: The function CVDenseGetReturnFlagName returns the name of the CVDENSE constant corresponding to flag.
Arguments: The only argument, of type int is a return flag from a CVDENSE function.
Return value: The return value is a string containing the name of the corresponding constant.
Notes

5.5.7.3 Band linear solver

The following optional outputs are available from the CVBAND module: workspace requirements, number of calls to the Jacobian routine, number of calls to the right-hand side routine for finite-difference Jacobian approximation, and last return value from a CVBAND function.

CVBandGetWorkSpace

Call

flag = CVBandGetWorkSpace(cvode_mem, &lenrwLS, &leniwLS);

Description

The function CVBandGetWorkSpace returns the CVBAND real and integer workspace sizes.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
lenrwLS: (long int) the number of realtype values in the CVBAND workspace.
leniwLS: (long int) the number of integer values in the CVBAND workspace.

Return value

The return value flag (of type int) is one of

CVBAND_SUCCESS: The optional output values have been successfully set.
CVBAND_MEM_NULL: The cvode_mem pointer is NULL.
CVBAND_LMEM_NULL: The CVBAND linear solver has not been initialized.

Notes

In terms of the problem size N and Jacobian half-bandwidths, the actual size of the real workspace is (2 mupper+3 mlower+2) N realtype words, and the actual size of the integer workspace is N integer words.

CVBandGetNumJacEvals

Call

flag = CVBandGetNumJacEvals(cvode_mem, &njevals);

Description

The function CVBandGetNumJacEvals returns the number of calls made to the banded Jacobian approximation function.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
njevals: (long int) the number of calls to the Jacobian function.

Return value

The return value flag (of type int) is one of

CVBAND_SUCCESS: The optional output value has been successfully set.
CVBAND_MEM_NULL: The cvode_mem pointer is NULL.
CVBAND_LMEM_NULL: The CVBAND linear solver has not been initialized.

Notes

CVBandGetNumRhsEvals

Call

flag = CVBandGetNumRhsEvals(cvode_mem, &nfevalsLS);

Description

The function CVBandGetNumRhsEvals returns the number of calls made to the user-supplied right-hand side function due to the finite difference banded Jacobian approximation.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
nfevalsLS: (long int) the number of calls made to the user-supplied right-hand side function.

Return value

The return value flag (of type int) is one of

CVBAND_SUCCESS: The optional output value has been successfully set.
CVBAND_MEM_NULL: The cvode_mem pointer is NULL.
CVBAND_LMEM_NULL: The CVBAND linear solver has not been initialized.

Notes

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

CVBandGetLastFlag

Call

flag = CVBandGetLastFlag(cvode_mem, &lsflag);

Description

The function CVBandGetLastFlag returns the value of the last return flag from a CVBAND routine.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
lsflag: (int) the value of the last return flag from a CVBAND function.

Return value

The return value flag (of type int) is one of

CVBAND_SUCCESS: The optional output value has been successfully set.
CVBAND_MEM_NULL: The cvode_mem pointer is NULL.
CVBAND_LMEM_NULL: The CVBAND linear solver has not been initialized.

Notes

If the CVBAND setup function failed (CVode returned CV_LSETUP_FAIL), the value of lsflag corresponds to the column index (numbered from one) of a diagonal element with value zero that was encountered during the LU factorization of the banded Jacobian matrix.

CVBandGetReturnFlagName
Call: name = CVBandGetReturnFlagName(flag);
Description: The function CVBandGetReturnFlagName returns the name of the CVBAND constant corresponding to flag.
Arguments: The only argument, of type int is a return flag from a CVBAND function.
Return value: The return value is a string containing the name of the corresponding constant.
Notes

5.5.7.4 Diagonal linear solver

The following optional outputs are available from the CVDIAG module: workspace requirements, number of calls to the right-hand side routine for finite-difference Jacobian approximation, and last return value from a CVDIAG function.

CVDiagGetWorkSpace

Call

flag = CVDiagGetWorkSpace(cvode_mem, &lenrwLS, &leniwLS);

Description

The function CVDiagGetWorkSpace returns the CVDIAG real and integer workspace sizes.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
lenrwLS: (long int) the number of realtype values in the CVDIAG workspace.
leniwLS: (long int) the number of integer values in the CVDIAG workspace.

Return value

The return value flag (of type int) is one of

CVDIAG_SUCCESS: The optional output valus have been successfully set.
CVDIAG_MEM_NULL: The cvode_mem pointer is NULL.
CVDIAG_LMEM_NULL: The CVDIAG linear solver has not been initialized.

Notes

In terms of the problem size N, the actual size of the real workspace is roughly 3N realtype words.

CVDiagGetNumRhsEvals

Call

flag = CVDiagGetNumRhsEvals(cvode_mem, &nfevalsLS);

Description

The function CVDiagGetNumRhsEvals returns the number of calls made to the user-supplied right-hand side function due to the finite difference Jacobian approximation.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
nfevalsLS: (long int) the number of calls made to the user-supplied right-hand side function.

Return value

The return value flag (of type int) is one of

CVDIAG_SUCCESS: The optional output value has been successfully set.
CVDIAG_MEM_NULL: The cvode_mem pointer is NULL.
CVDIAG_LMEM_NULL: The CVDIAG linear solver has not been initialized.

Notes

The number of diagonal approximate Jacobians formed is equal to the number of calls made to the linear solver setup function (see CVodeGetNumLinSolvSetups).

CVDiagGetLastFlag

Call

flag = CVDiagGetLastFlag(cvode_mem, &lsflag);

Description

The function CVDiagGetLastFlag returns the last return value from a CVDIAG routine.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
lsflag: (int) the value of the last return flag from a CVDIAG function.

Return value

The return value flag (of type int) is one of

CVDIAG_SUCCESS: The optional output value has been successfully set.
CVDIAG_MEM_NULL: The cvode_mem pointer is NULL.
CVDIAG_LMEM_NULL: The CVDIAG linear solver has not been initialized.

Notes

If the CVDIAG setup function failed (CVode returned CV_LSETUP_FAIL), the value of lsflag is equal to CVDIAG_INV_FAIL, indicating that a diagonal element with value zero was encountered. The same value is also returned if the CVDIAG solve function failed (CVode returned CV_LSOLVE_FAIL).

CVDiagGetReturnFlagName
Call: name = CVDiagGetReturnFlagName(flag);
Description: The function CVDiagGetReturnFlagName returns the name of the CVDIAG constant corresponding to flag.
Arguments: The only argument, of type int is a return flag from a CVDIAG function.
Return value: The return value is a string containing the name of the corresponding constant.
Notes

5.5.7.5 SPILS linear solvers

The following optional outputs are available from the CVSPILS modules: workspace requirements, number of linear iterations, number of linear convergence failures, number of calls to the preconditioner setup and solve routines, number of calls to the Jacobian-vector product routine, number of calls to the right-hand side routine for finite-difference Jacobian-vector product approximation, and last return value from a linear solver function.

CVSpilsGetWorkSpace

Call

flag = CVSpilsGetWorkSpace(cvode_mem, &lenrwLS, &leniwLS);

Description

The function CVSpilsGetWorkSpace returns the global sizes of the CVSPGMR real and integer workspaces.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
lenrwLS: (long int) the number of realtype values in the CVSPILS workspace.
leniwLS: (long int) the number of integer values in the CVSPILS workspace.

Return value

The return value flag (of type int) is one of

CVSPILS_SUCCESS: The optional output value has been successfully set.
CVSPILS_MEM_NULL: The cvode_mem pointer is NULL.
CVSPILS_LMEM_NULL: The CVSPILS linear solver has not been initialized.

Notes

In terms of the problem size N and maximum subspace size maxl, the actual size of the real workspace is roughly:
(maxl+5)*N + maxl *( maxl+4) + 1 realtype words for CVSPGMR,
9*N realtype words for CVSPBCG,
and 11*N realtype words for IDASPTFQMR.

In a parallel setting, the above values are global -- summed over all processors.

CVSpilsGetNumLinIters

Call

flag = CVSpilsGetNumLinIters(cvode_mem, &nliters);

Description

The function CVSpilsGetNumLinIters returns the cumulative number of linear iterations.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
nliters: (long int) the current number of linear iterations.

Return value

The return value flag (of type int) is one of

CVSPILS_SUCCESS: The optional output value has been successfully set.
CVSPILS_MEM_NULL: The cvode_mem pointer is NULL.
CVSPILS_LMEM_NULL: The CVSPILS linear solver has not been initialized.

Notes

CVSpilsGetNumConvFails

Call

flag = CVSpilsGetNumConvFails(cvode_mem, &nlcfails);

Description

The function CVSpilsGetNumConvFails returns the cumulative number of linear convergence failures.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
nlcfails: (long int) the current number of linear convergence failures.

Return value

The return value flag (of type int) is one of

CVSPILS_SUCCESS: The optional output value has been successfully set.
CVSPILS_MEM_NULL: The cvode_mem pointer is NULL.
CVSPILS_LMEM_NULL: The CVSPILS linear solver has not been initialized.

Notes

CVSpilsGetNumPrecEvals

Call

flag = CVSpilsGetNumPrecEvals(cvode_mem, &npevals);

Description

The function CVSpilsGetNumPrecEvals returns the number of preconditioner evaluations, i.e., the number of calls made to psetup with jok = FALSE.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
npevals: (long int) the current number of calls to psetup.

Return value

The return value flag (of type int) is one of

CVSPILS_SUCCESS: The optional output value has been successfully set.
CVSPILS_MEM_NULL: The cvode_mem pointer is NULL.
CVSPILS_LMEM_NULL: The CVSPILS linear solver has not been initialized.

Notes

CVSpilsGetNumPrecSolves

Call

flag = CVSpilsGetNumPrecSolves(cvode_mem, &npsolves);

Description

The function CVSpilsGetNumPrecSolves returns the cumulative number of calls made to the preconditioner solve function, psolve.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
npsolves: (long int) the current number of calls to psolve.

Return value

The return value flag (of type int) is one of

CVSPILS_SUCCESS: The optional output value has been successfully set.
CVSPILS_MEM_NULL: The cvode_mem pointer is NULL.
CVSPILS_LMEM_NULL: The CVSPILS linear solver has not been initialized.

Notes

CVSpilsGetNumJtimesEvals

Call

flag = CVSpilsGetNumJtimesEvals(cvode_mem, &njvevals);

Description

The function CVSpilsGetNumJtimesEvals returns the cumulative number made to the Jacobian-vector function, jtimes.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
njvevals: (long int) the current number of calls to jtimes.

Return value

The return value flag (of type int) is one of

CVSPILS_SUCCESS: The optional output value has been successfully set.
CVSPILS_MEM_NULL: The cvode_mem pointer is NULL.
CVSPILS_LMEM_NULL: The CVSPILS linear solver has not been initialized.

Notes

CVSpilsGetNumRhsEvals

Call

flag = CVSpilsGetNumRhsEvals(cvode_mem, &nfevalsLS);

Description

The function CVSpilsGetNumRhsEvals returns the number of calls to the user right-hand side function for finite difference Jacobian-vector product approximation.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
nfevalsLS: (long int) the number of calls to the user right-hand side function.

Return value

The return value flag (of type int) is one of

CVSPILS_SUCCESS: The optional output value has been successfully set.
CVSPILS_MEM_NULL: The cvode_mem pointer is NULL.
CVSPILS_LMEM_NULL: The CVSPILS linear solver has not been initialized.

Notes

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

CVSpilsGetLastFlag

Call

flag = CVSpilsGetLastFlag(cvode_mem, &lsflag);

Description

The function CVSpilsGetLastFlag returns the last return value from a CVSPILS routine.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
flag: (int) the value of the last return flag from a CVSPILS function.

Return value

The return value flag (of type int) is one of

CVSPILS_SUCCESS: The optional output value has been successfully set.
CVSPILS_MEM_NULL: The cvode_mem pointer is NULL.
CVSPILS_LMEM_NULL: The CVSPILS linear solver has not been initialized.

Notes

If the CVSPILS setup function failed (CVode returned CV_LSETUP_FAIL), lsflag will be SPGMR_PSET_FAIL_UNREC, SPBCG_PSET_FAIL_UNREC, or SPTFQMR_PSET_FAIL_UNREC.

If the CVSPGMR solve function failed (CVode returned CV_LSOLVE_FAIL), lsflag contains the error return flag from SpgmrSolve and will be one of: SPGMR_MEM_NULL, indicating that the SPGMR memory is NULL; SPGMR_ATIMES_FAIL_UNREC, indicating an unrecoverable failure in the Jacobian-times-vector function; SPGMR_PSOLVE_FAIL_UNREC, indicating that the preconditioner solve function psolve failed unrecoverably; SPGMR_GS_FAIL, indicating a failure in the Gram-Schmidt procedure; or SPGMR_QRSOL_FAIL, indicating that the matrix R was found to be singular during the QR solve phase.

If the CVSPBCG solve function failed (CVode returned CV_LSOLVE_FAIL), lsflag contains the error return flag from SpbcgSolve and will be one of: SPBCG_MEM_NULL, indicating that the SPBCG memory is NULL; SPBCG_ATIMES_FAIL_UNREC, indicating an unrecoverable failure in the Jacobian-times-vector function; or SPBCG_PSOLVE_FAIL_UNREC, indicating that the preconditioner solve function psolve failed unrecoverably.

If the CVSPTFQMR solve function failed (CVode returned CV_LSOLVE_FAIL), lsflag contains the error return flag from SptfqmrSolve and will be one of: SPTFQMR_MEM_NULL, indicating that the SPTFQMR memory is NULL; SPTFQMR_ATIMES_FAIL_UNREC, indicating an unrecoverable failure in the Jacobian-times-vector function; or SPTFQMR_PSOLVE_FAIL_UNREC, indicating that the preconditioner solve function psolve failed unrecoverably.

CVSpilsGetReturnFlagName
Call: name = CVSpilsGetReturnFlagName(flag);
Description: The function CVSpilsGetReturnFlagName returns the name of the CVSPILS constant corresponding to flag.
Arguments: The only argument, of type int is a return flag from a CVSPILS function.
Return value: The return value is a string containing the name of the corresponding constant.
Notes

5.5.8 CVODES reinitialization function

The function CVodeReInit reinitializes the main CVODES solver for the solution of a problem, where a prior call to CVodeMalloc has been made. The new problem must have the same size as the previous one. CVodeReInit performs the same input checking and initializations that CVodeMalloc does, but does no memory allocation as it assumes that the existing internal memory is sufficient for the new problem.

The use of CVodeReInit requires that the maximum method order, denoted by maxord, be no larger for the new problem than for the previous problem. This condition is automatically fulfilled if the multistep method parameter lmm is unchanged (or changed from CV_ADAMS to CV_BDF) and the default value for maxord is specified.

If there are changes to the linear solver specifications, make the appropriate CV*Set* calls, as described in §5.5.3

CVodeReInit

Call

flag = CVodeReInit(cvode_mem, f, t0, y0, itol, reltol, abstol);

Description

The function CVodeReInit provides required problem specifications and reinitializes CVODES.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
f: (CVRhsFn) is the C function which computes f in the ODE. This function has the form f(N, t, y, ydot, f_data) (for full details see §5.6).
t0: (realtype) is the initial value of t.
y0: (N_Vector) is the initial value of y.
itol: (int) is one of CV_SS, CV_SV, or CV_WF, where itol = CV_SS indicates scalar relative error tolerance and scalar absolute error tolerance, while itol = CV_SV indicates scalar relative error tolerance and vector absolute error tolerance. The latter choice is important when the absolute error tolerance needs to be different for each component of the ODE. If itol=CV_WF, the arguments reltol and abstol are ignored and the user is expected to provide a function to evaluate the error weight vector W from (3.7). See CVodeSetEwtFn in §5.5.5.1.
reltol: (realtype) is the relative error tolerance.
abstol: (void *) is a pointer to the absolute error tolerance. If itol=CV_SS, abstol must be a pointer to a realtype variable. If itol=CV_SV, abstol must be an N_Vector variable.

Return value

The return flag flag (of type int) will be one of the following:

CV_SUCCESS: The call to CVodeReInit was successful.
CV_MEM_NULL: The CVODES memory block was not initialized through a previous call to CVodeCreate.
CV_NO_MALLOC: Memory space for the CVODES memory block was not allocated through a previous call to CVodeMalloc.
CV_ILL_INPUT: An input argument to CVodeReInit has an illegal value.

Notes

If an error occurred, CVodeReInit also sends an error message to the error handler function.

It is the user's responsibility to provide compatible itol and abstol arguments.

5.6 User-supplied functions

The user-supplied functions consist of one function defining the ODE, (optionally) a function that handles error and warning messages, (optionally) a function that provides the error weight vector, (optionally) a function that provides Jacobian-related information for the linear solver (if Newton iteration is chosen), and (optionally) one or two functions that define the preconditioner for use in any of the Krylov iterative algorithms.

5.6.1 ODE right-hand side

The user must provide a function of type CVRhsFn defined as follows:

CVRhsFn

Definition

	`typedef int (*CVRhsFn)(`		`realtype t, N_Vector y, N_Vector ydot,`
			`void *f_data);`

Purpose

This function computes the ODE right-hand side for a given value of the independent variable t and state vector y.

Arguments

t: is the current value of the independent variable.
y: is the current value of the dependent variable vector, y(t).
ydot: is the output vector f (t, y).
f_data: is the f_data pointer passed to CVodeSetFdata.

Return value

A CVRhsFn should return 0 if successful, a positive value if a recoverable error occurred (in which case CVODES will attempt to correct), or a negative value if it failed unrecoverably (in which case the integration is halted and CV_RHSFUNC_FAIL is returned).

Notes

Allocation of memory for ydot is handled within CVODES.

For efficiency considerations, the right-hand side function is not evaluated at the converged solution of the nonlinear solver. Therefore, a recoverable error in CVRhsFn at that point cannot be corrected (as it will occur when the right-hand side function is called the first time during the following integration step and a successful step cannot be undone). However, if the use program also includes quadrature integration, the state variables can be checked for legality in the call to CVQuadRhsFn which is called at the converged solution of the nonlinear system and therefore CVODES can be flagged to attempt to recover from such a situation. Also, if sensitivity analysis is performed with one of the staggered methods, the ODE right-hand side function is called at the converged solution of the nonlinear system and a recoverable error at that point will be captured and CVODES will try to correct it.

There are two other situations in which recovery is not possible even if the right-hand side function returns a recoverable error flag. This include the situation when this occurrs at the very first call to the CVRhsFn (in which case CVODES returns CV_FIRST_RHSFUNC_ERR) or if a recoverable error is reported when CVRhsFn is called after an error test failure, while the linear multistep method order is equal to 1 (in which case CVODES returns CV_UNREC_RHSFUNC_ERR).

5.6.2 Error message handler function

As an alternative to the default behavior of directing error and warning messages to the file pointed to by errfp (see CVSetErrFile), the user may provide a function of type CVErrHandlerFn to process any such messages. The function type CVErrHandlerFn is defined as follows:

CVErrHandlerFn

Definition

	`typedef void (*CVErrHandlerFn)(`		`int error_code,`
			`const char module, const char function,`
			`char msg, void eh_data);`

Purpose

This function processes error and warning messages from CVODES and its sub-modules.

Arguments

error_code: is the error code.
module: is the name of the CVODES module reporting the error.
function: is the name of the function in which the error occurred.
msg: is the error message.
eh_data: is a pointer to user data, the same as the eh_data parameter passed to CVodeSetErrHandlerFn.

Return value

A CVErrHandlerFn function has no return value.

Notes

error_code is negative for errors and positive (CV_WARNING) for warnings. If a function returning a pointer to memory (e.g. CVBBDPrecAlloc) encounters an error, it sets error_code to 0 before returning NULL.

5.6.3 Error weight function

As an alternative to providing the relative and absolute tolerances, the user may provide a function of type CVEwtFn to compute a vector ewt containing the weights in the WRMS norm | v|_WRMS = $\sqrt{{(1/N)\sum_1^N (W_i \cdot v_i)^2}}$ . The function type CVEwtFn is defined as follows:

CVEwtFn

Definition

typedef int (*CVEwtFn)(N_Vector y, N_Vector ewt, void *e_data);

Purpose

This function computes the WRMS error weights for the vector y.

Arguments

y: is the value of the vector for which the WRMS norm must be computed.
ewt: is the output vector containing the error weights.
e_data: is the e_data pointer passed to CVodeSetEwtFn.

Return value

A CVEwtFn function type must return 0 if it successfuly set the error weights and -1 otherwise. In case of failure, a message is printed and the integration stops.

Notes

Allocation of memory for ewt is handled within CVODES.

The error weight vector must have all components positive. It is the user's responsiblity to perform this test and return -1 if it is not satisfied.

5.6.4 Jacobian information (direct method with dense Jacobian)

If the direct linear solver with dense treatment of the Jacobian is used (i.e., CVDense is called in Step 7 of §5.4), the user may provide a function of type CVDenseJacFn defined by:

CVDenseJacFn

Definition

	`typedef (*CVDenseJacFn)(`		`long int N, DenseMat J, realtype t,`
			`N_Vector y, N_Vector fy, void *jac_data,`
			`N_Vector tmp1, N_Vector tmp2, N_Vector tmp3);`

Purpose

This function computes the dense Jacobian J = $\partial$ f / $\partial$ y (or an approximation to it).

Arguments

N: is the problem size.
J: is the output Jacobian matrix.
t: is the current value of the independent variable.
y: is the current value of the dependent variable vector, namely the predicted value of y(t).
fy: is the current value of the vector f (t, y).
jac_data: is the jac_data pointer passed to CVDenseSetJacFn.
tmp1
tmp2
tmp3: are pointers to memory allocated for variables of type N_Vector which can be used by CVDenseJacFn as temporary storage or work space.

Return value

A CVDenseJacFn should return 0 if successful, a positive value if a recoverable error occurred (in which case CVODES will attempt to correct, while CVDENSE sets last_flag on CVDENSE_JACFUNC_RECVR), or a negative value if it failed unrecoverably (in which case the integration is halted, CVode returns CV_LSETUP_FAIL and CVDENSE sets last_flag on CVDENSE_JACFUNC_UNRECVR).

Notes

A user-supplied dense Jacobian function must load the N by N dense matrix J with an approximation to the Jacobian matrix J at the point (t, y). Only nonzero elements need to be loaded into J because J is set to the zero matrix before the call to the Jacobian function. The type of J is DenseMat.

The accessor macros DENSE_ELEM and DENSE_COL allow the user to read and write dense matrix elements without making explicit references to the underlying representation of the DenseMat type. DENSE_ELEM(J, i, j) references the (i, j)-th element of the dense matrix J (i, j = 0...N - 1). This macro is meant for small problems for which efficiency of access is not a major concern. Thus, in terms of the indices m and n ranging from 1 to N, the Jacobian element J_{m, n} can be set using the statement DENSE_ELEM(J, m-1, n-1) = J_{m, n}. Alternatively, DENSE_COL(J, j) returns a pointer to the first element of the j-th column of J (j = 0...N - 1), and the elements of the j-th column can then be accessed using ordinary array indexing. Consequently, J_{m, n} can be loaded using the statements col_n = DENSE_COL(J, n-1); col_n[m-1] = J_{m, n}. For large problems, it is more efficient to use DENSE_COL than to use DENSE_ELEM. Note that both of these macros number rows and columns starting from 0.

The DenseMat type and accessor macros DENSE_ELEM and DENSE_COL are documented in §10.1.

If the user's CVDenseJacFn function uses difference quotient approximations, then it may need to access quantities not in the argument list. These include the current step size, the error weights, etc. To obtain these, use the CVodeGet* functions described in §5.5.7.1. The unit roundoff can be accessed as UNIT_ROUNDOFF defined in sundials_types.h.

5.6.5 Jacobian information (direct method with banded Jacobian)

If the direct linear solver with banded treatment of the Jacobian is used (i.e. CVBand is called in Step 7 of §5.4), the user may provide a function of type CVBandJacFn defined as follows:

CVBandJacFn

Definition

	`typedef int (*CVBandJacFn)(`		`long int N, long int mupper,`
			`long int mlower, BandMat J, realtype t,`
			`N_Vector y, N_Vector fy, void *jac_data,`
			`N_Vector tmp1, N_Vector tmp2, N_Vector tmp3);`

Purpose

This function computes the banded Jacobian J = $\partial$ f / $\partial$ y (or a banded approximation to it).

Arguments

N: is the problem size.
mlower
mupper: are the lower and upper half-bandwidths of the Jacobian.
J: is the output Jacobian matrix.
t: is the current value of the independent variable.
y: is the current value of the dependent variable vector, namely the predicted value of y(t).
fy: is the current value of the vector f (t, y).
jac_data: is the jac_data pointer passed to CVBandSetJacFn.
tmp1
tmp2
tmp3: are pointers to memory allocated for variables of type N_Vector which can be used by CVBandJacFn as temporary storage or work space.

Return value

A CVBandJacFn should return 0 if successful, a positive value if a recoverable error occurred (in which case CVODES will attempt to correct, while CVBAND sets last_flag on CVBAND_JACFUNC_RECVR), or a negative value if it failed unrecoverably (in which case the integration is halted, CVode returns CV_LSETUP_FAIL and CVBAND sets last_flag on CVBAND_JACFUNC_UNRECVR).

Notes

A user-supplied band Jacobian function must load the band matrix J of type BandMat with the elements of the Jacobian J(t, y) at the point (t,y). Only nonzero elements need to be loaded into J because J is initialized to the zero matrix before the call to the Jacobian function.

The accessor macros BAND_ELEM, BAND_COL, and BAND_COL_ELEM allow the user to read and write band matrix elements without making specific references to the underlying representation of the BandMat type. BAND_ELEM(J, i, j) references the (i, j)-th element of the band matrix J, counting from 0. This macro is meant for use in small problems for which efficiency of access is not a major concern. Thus, in terms of the indices m and n ranging from 1 to N with (m, n) within the band defined by mupper and mlower, the Jacobian element J_{m, n} can be loaded using the statement BAND_ELEM(J, m-1, n-1) = J_{m, n}. The elements within the band are those with -mupper $\le$ m-n $\le$ mlower. Alternatively, BAND_COL(J, j) returns a pointer to the diagonal element of the j-th column of J, and if we assign this address to realtype *col_j, then the i-th element of the j-th column is given by BAND_COL_ELEM(col_j, i, j), counting from 0. Thus, for (m, n) within the band, J_{m, n} can be loaded by setting col_n = BAND_COL(J, n-1); BAND_COL_ELEM(col_n, m-1, n-1) = J_{m, n}. The elements of the j-th column can also be accessed via ordinary array indexing, but this approach requires knowledge of the underlying storage for a band matrix of type BandMat. The array col_n can be indexed from -mupper to mlower. For large problems, it is more efficient to use BAND_COL and BAND_COL_ELEM than to use the BAND_ELEM macro. As in the dense case, these macros all number rows and columns starting from 0.

The BandMat type and the accessor macros BAND_ELEM, BAND_COL and BAND_COL_ELEM are documented in §10.2.

If the user's CVBandJacFn function uses difference quotient approximations, then it may need to access quantities not in the argument list. These include the current step size, the error weights, etc. To obtain these, use the CVodeGet* functions described in §5.5.7.1. The unit roundoff can be accessed as UNIT_ROUNDOFF defined in sundials_types.h.

5.6.6 Jacobian information (matrix-vector product)

If one of the Krylov iterative linear solvers SPGMR, SPBCG, or SPTFQMR is selected (CVSp* is called in step 7 of §5.4), the user may provide a function of type CVSpilsJacTimesVecFn in the following form:

CVSpilsJacTimesVecFn

Definition

	`typedef int (*CVSpilsJacTimesVecFn)`		`(N_Vector v, N_Vector Jv,`
			`realtype t, N_Vector y, N_Vector fy,`
			`void *jac_data, N_Vector tmp);`

Purpose

This function computes the product Jv = ( $\partial$ f / $\partial$ y)v (or an approximation to it).

Arguments

v: is the vector by which the Jacobian must be multiplied.
Jv: is the output vector computed.
t: is the current value of the independent variable.
y: is the current value of the dependent variable vector.
fy: is the current value of the vector f (t, y).
jac_data: is the jac_data pointer passed to CVSp*SetJacTimesVecFn.
tmp: is a pointer to memory allocated for a variable of type N_Vector which can be used for work space.

Return value

The value to be returned by the Jacobian-vector product function should be 0 if successful. Any other return value will result in an unrecoverable error of the SPGMR generic solver, in which case the integration is halted.

Notes

If the user's CVSpilsJacTimesVecFn function uses difference quotient approximations, it may need to access quantities not in the argument list. These include the current step size, the error weights, etc. To obtain these, use the CVodeGet* functions described in §5.5.7.1. The unit roundoff can be accessed as UNIT_ROUNDOFF defined in sundials_types.h.

5.6.7 Preconditioning (linear system solution)

If preconditioning is used, then the user must provide a C function to solve the linear system Pz = r, where P may be either a left or right preconditioner matrix. This function must be of type CVSpilsPrecSolveFn, defined as follows:

CVSpilsPrecSolveFn

Definition

	`typedef int (*CVSpilsPrecSolveFn)(`		`realtype t, N_Vector y, N_Vector fy,`
			`N_Vector r, N_Vector z,`
			`realtype gamma, realtype delta,`
			`int lr, void *p_data, N_Vector tmp);`

Purpose

This function solves the preconditioned system Pz = r.

Arguments

t: is the current value of the independent variable.
y: is the current value of the dependent variable vector.
fy: is the current value of the vector f (t, y).
r: is the right-hand side vector of the linear system.
z: is the computed output vector.
gamma: is the scalar $\gamma$ appearing in the Newton matrix given by M = I - $\gamma$ J.
delta: is an input tolerance to be used if an iterative method is employed in the solution. In that case, the residual vector Res = r - Pz of the system should be made less than delta in the weighted l₂ norm, i.e., $\sqrt{{\sum_i (Res_i \cdot ewt_i)^2 }}$ < delta. To obtain the N_Vector ewt call CVodeGetErrWeights (see §5.5.7.1).
lr: is an input flag indicating whether the preconditioner solve function is to use the left preconditioner (lr = 1) or the right preconditioner (lr = 2);
p_data: is the p_data pointer passed to CVSp*SetPreconditioner.
tmp: is a pointer to memory allocated for a variable of type N_Vector which can be used for work space.

Return value

The value to be returned by the preconditioner solve function is a flag indicating whether it was successful. This value should be 0 if successful, positive for a recoverable error (in which case the step will be retried), or negative for an unrecoverable error (in which case the integration is halted).

Notes

5.6.8 Preconditioning (Jacobian data)

If the user's preconditioner requires that any Jacobian-related data be preprocessed or evaluated, then this needs to be done in a user-supplied C function of type CVSpilsPrecSetupFn, defined as follows:

CVSpilsPrecSetupFn

Definition

	`typedef int (*CVSpilsPrecSetupFn`		`)(realtype t, N_Vector y, N_Vector fy,`
			`booleantype jok, booleantype *jcurPtr,`
			`realtype gamma, void *p_data,`
			`N_Vector tmp1, N_Vector tmp2,`
			`N_Vector tmp3);`

Purpose

This function preprocesses and/or evaluates Jacobian-related data needed by the preconditioner.

Arguments

The arguments of a CVSpilsPrecSetupFn are as follows:

t: is the current value of the independent variable.
y: is the current value of the dependent variable vector, namely the predicted value of y(t).
fy: is the current value of the vector f (t, y).
jok: is an input flag indicating whether the Jacobian-related data needs to be updated. The jok argument provides for the reuse of Jacobian data in the preconditioner solve function. jok = FALSE means that the Jacobian-related data must be recomputed from scratch. jok = TRUE means that the Jacobian data, if saved from the previous call to this function, can be reused (with the current value of gamma). A call with jok = TRUE can only occur after a call with jok = FALSE.
jcurPtr: is a pointer to a flag which should be set to TRUE if Jacobian data was recomputed, or set to FALSE if Jacobian data was not recomputed, but saved data was still reused.
gamma: is the scalar $\gamma$ appearing in the Newton matrix M = I - $\gamma$ P.
p_data: is the p_data pointer passed to CVSp*SetPreconditioner.
tmp1
tmp2
tmp3: are pointers to memory allocated for variables of type N_Vector which can be used by CVSpilsPrecSetupFn as temporary storage or work space.

Return value

The value to be returned by the preconditioner setup function is a flag indicating whether it was successful. This value should be 0 if successful, positive for a recoverable error (in which case the step will be retried), or negative for an unrecoverable error (in which case the integration is halted).

Notes

The operations performed by this function might include forming a crude approximate Jacobian, and performing an LU factorization of the resulting approximation to M = I - $\gamma$ J.

Each call to the preconditioner setup function is preceded by a call to the CVRhsFn user function with the same (t,y) arguments. Thus, the preconditioner setup function can use any auxiliary data that is computed and saved during the evaluation of the ODE right-hand side.

This function is not called in advance of every call to the preconditioner solve function, but rather is called only as often as needed to achieve convergence in the Newton iteration.

If the user's CVSpilsPrecSetupFn function uses difference quotient approximations, it may need to access quantities not in the call list. These include the current step size, the error weights, etc. To obtain these, use the CVodeGet* functions described in §5.5.7.1. The unit roundoff can be accessed as UNIT_ROUNDOFF defined in sundials_types.h.

5.7 Integration of pure quadrature equations

If the system of ODEs contains pure quadratures, it is more efficient to treat them separately by excluding them from the nonlinear solution stage. To do this, begin by excluding the quadrature variables from the vector y and the quadrature equations from within f. The following is an overview of the sequence of calls in a user's main program in this situation. Steps that are unchanged from the skeleton program presented in §5.4 are grayed out.

[P] Initialize MPI
Set problem dimensions
[S] Set N to the problem size N (excluding quadrature variables), and Nq to the number of quadrature variables.
[P] Set Nlocal to the local vector length (excluding quadrature variables), and Nqlocal to the local number of quadrature variables.
Set vector of initial values
Create CVODES object
Allocate internal memory
Set optional inputs
Attach linear solver module
Set linear solver optional inputs
Set vector of initial values for quadrature variables
Typically, the quadrature variables should be initialized to 0.
Initialize quadrature integration
Call CVodeQuadMalloc to specify the quadrature equation right-hand side function and to allocate internal memory related to quadrature integration. See §5.7.1 for details.
Set optional inputs for quadrature integration
Call CVodeSetQuadFdata to specify user data required for the evaluation of the quadrature equation right-hand side. Call CVodeSetQuadErrCon to indicate whether or not quadrature variables shoule be used in the step size control mechanism, and to specify the integration tolerances for quadrature variables. See §5.7.4 for details.
Advance solution in time
Extract quadrature variables
Call CVodeGetQuad to obtain the values of the quadrature variables at the current time. See §5.7.3 for details.
Get optional outputs
Get quadrature optional outputs
Call CVodeGetQuad* functions to obtain optional output related to the integration of quadratures. See §5.7.5 for details.
Deallocate memory for solution vector and for the vector of quadrature variables
Free solver memory
[P] Finalize MPI

CVodeQuadMalloc can be called and quadrature-related optional inputs (step 11 above) can be set, anywhere between steps 4 and 12.

5.7.1 Quadrature initialization functions

The function CVodeQuadMalloc activates integration of quadrature equations and allocates internal memory related to these calculations. The form of the call to this function is as follows:

CVodeQuadMalloc

Call

flag = CVodeQuadMalloc(cvode_mem, fQ, yQ0);

Description

The function CVodeQuadMalloc provides required problem specifications, allocates internal memory, and initializes quadrature integration.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block returned by CVodeCreate.
fQ: (CVQuadRhsFn) is the C function which computes f_Q, the right-hand side of the quadrature equations. This function has the form fQ(t, y, yQdot, fQ_data) (for full details see §5.7.6).
yQ0: (N_Vector) is the initial value of y_Q.

Return value

The return value flag (of type int) will be one of the following:

CV_SUCCESS: The call to CVodeQuadMalloc was successful.
CV_MEM_NULL: The CVODES memory was not initialized by a prior call to CVodeCreate.
CV_MEM_FAIL: A memory allocation request failed.

Notes

If an error occured, CVodeQuadMalloc also sends an error message to the error handler function.

In terms of the number of quadrature variables N_q and maximum method order maxord, the size of the real workspace is increased by:

Base value: lenrw = lenrw + (maxord+5)N_q
With itolQ = CV_SV (see CVodeSetQuadErrCon): lenrw = lenrw + N_q

the size of the integer workspace is increased by:

Base value: leniw = leniw + (maxord+5)N_q
With itolQ = CV_SV: leniw = leniw + N_q

The function CVodeQuadReInit, useful during the solution of a sequence of problems of same size, reinitializes the quadrature related internal memory and must follow a call to CVodeQuadMalloc (and maybe a call to CVodeReInit). The number Nq of quadratures is assumed to be unchanged from the prior call to CVodeQuadMalloc. The call to the CVodeQuadReInit function has the form:

CVodeQuadReInit

Call

flag = CVodeQuadReInit(cvode_mem, fQ, yQ0);

Description

The function CVodeQuadReInit provides required problem specifications and reinitializes the quadrature integration.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
fQ: (CVQuadRhsFn) is the C function which computes f_Q, the right-hand side of the quadrature equations.
yQ0: (N_Vector) is the initial value of y_Q.

Return value

The return value flag (of type int) will be one of the following:

CV_SUCCESS: The call to CVodeReInit was successful.
CV_MEM_NULL: The CVODES memory was not initialized by a prior call to CVodeCreate.
CV_NO_QUAD: Memory space for the quadrature integration was not allocated by a prior call to CVodeQuadMalloc.

Notes

If an error occured, CVodeQuadReInit also sends an error message to the error handler function.

5.7.2 CVODE solver function

Even if quadrature integration was enabled, the call to the main solver function CVode is exactly the same as in §5.5.4. However, in this case the return value flag can also be one of the following:

CV_QRHSFUNC_FAIL: The quadrature right-hand side function failed in an unrecoverable manner.
CV_FIRST_QRHSFUNC_FAIL: The quadrature right-hand side function failed at the first call.
CV_REPTD_QRHSFUNC_ERR: Convergence tests occurred too many times due to repeated recoverable errors in the quadrature right-hand side function. The CV_REPTD_RHSFUNC_ERR will also be returned if the quadrature right-hand side function had repeated recoverable errors during the estimation of an initial step size (assuming the quadrature variables are included in the error tests).
CV_UNREC_RHSFUNC_ERR: The quadrature right-hand function had a recoverable error, but no recovery was possible. This failure mode is rare, as it can occur only if the quadrature right-hand side function fails recoverably after an error test failed while at order one.

5.7.3 Quadrature extraction functions

If quadrature integration has been initialized by a call to CVodeQuadMalloc, or reinitialized by a call to CVodeQuadReInit, then CVODES computes both a solution and quadratures at time t. However, CVode will still return only the solution y in y. Solution quadratures can be obtained using the following function:

CVodeGetQuad

Call

flag = CVodeGetQuad(cvode_mem, t, yQ);

Description

The function CVodeGetQuad returns the quadrature solution vector after a successful return from CVode.

Arguments

cvode_mem: (void *) pointer to the memory previously allocated by CVodeMalloc.
t: (realtype) the time at which quadrature information is requested. The time t must fall within the interval defined by the last successful step taken by CVODES.
yQ: (N_Vector) the computed quadrature vector.

Return value

The return value flag of CVodeGetQuad is one of:

CV_SUCCESS: CVodeGetQuad was successful.
CV_MEM_NULL: cvode_mem was NULL.
CV_NO_QUAD: Quadrature integration was not initialized.
CV_BAD_DKY: yQ is NULL.
CV_BAD_T: The time t is not in the allowed range.

Notes

In case of an error return, an error message is also sent to the error handler function.

The function CVodeGetQuadDky computes the k-th derivatives of the interpolating polynomials for the quadrature variables at time t. This function is called by CVodeGetQuad with k = 0, but may also be called directly by the user.

CVodeGetQuadDky

Call

flag = CVodeGetQuadDky(cvode_mem, t, k, dkyQ);

Description

The function CVodeGetQuadDky returns derivatives of the quadrature solution vector after a successful return from CVode.

Arguments

cvode_mem: (void *) pointer to the memory previously allocated by CVodeMalloc.
t: (realtype) the time at which quadrature information is requested. The time t must fall within the interval defined by the last successful step taken by CVODES.
k: (int) order of the requested derivative.
dkyQ: (N_Vector) the vector containing the derivative. This vector must be allocated by the user.

Return value

The return value flag of CVodeGetQuadDky is one of:

CV_SUCCESS: CVodeGetQuadDky succeeded.
CV_MEM_NULL: The pointer to cvode_mem was NULL.
CV_NO_QUAD: Quadrature integration was not initialized.
CV_BAD_DKY: The vector dkyQ is NULL.
CV_BAD_K: k is not in the range 0, 1,..., q_u.
CV_BAD_T: The time t is not in the allowed range.

Notes

In case of an error return, an error message is also sent to the error handler function.

5.7.4 Optional inputs for quadrature integration

CVODES provides the following optional input functions to control the integration of quadrature equations.

CVodeSetQuadFdata

Call

flag = CVodeSetQuadFdata(cvode_mem, fQ_data);

Description

The function CVodeSetQuadFdata specifies the user-defined data block fQ_data and attaches it to the main CVODES memory block.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
fQ_data: (void *) pointer to the user data.

Return value

The return value flag (of type int) is one of:

CV_SUCCESS: The optional value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.

Notes

If fQ_data is not specified, a NULL pointer is passed to all user-supplied functions that have it as an argument. Note that fQ_data can be the same as the pointer f_data set through CVodeSetFdata.

CVodeSetQuadErrCon

Call

flag = CVodeSetQuadErrCon(cvode_mem, errconQ, itolQ, reltolQ, abstolQ);

Description

The function CVodeSetQuadErrCon specifies whether or not the quadrature variables should be used in the step size control mechanism, and if so, specifies the integration tolerances for the quadrature variables.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
errconQ: (booleantype) specifies whether quadrature variables are included (TRUE) or not (FALSE) in the error control mechanism. If errconQ=FALSE, the following three arguments are ignored.
itolQ: (int) is either CV_SS or CV_SV, where itolQ = CV_SS indicates scalar relative error tolerance and scalar absolute error tolerance, while itolQ = CV_SV indicates scalar relative error tolerance and vector absolute error tolerance. The latter choice is important when the absolute error tolerance needs to be different for each quadrature variable.
reltolQ: (realtype *) is a pointer to the relative error tolerance.
abstolQ: (void *) is a pointer to the absolute error tolerance. If itolQ=CV_SS, abstolQ must be a pointer to a realtype variable. If itolQ = CV_SV, abstolQ must be an N_Vector variable.

Return value

The return value flag (of type int) is one of:

CV_SUCCESS: The optional value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.
CV_ILL_INPUT: An input argument to CVodeSetQuadErrCon has an illegal value.

Notes

By default, errconQ is set to FALSE.

It is illegal to call CVodeSetQuadErrCon before a call to CVodeQuadMalloc.

5.7.5 Optional outputs for quadrature integration

CVODES provides the following functions that can be used to obtain solver performance information related to quadrature integration.

CVodeGetQuadNumRhsEvals

Call

flag = CVodeGetQuadNumRhsEvals(cvode_mem, &nfQevals);

Description

The function CVodeGetQuadNumRhsEvals returns the number of calls made to the user's quadrature right-hand side function.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
nfQevals: (long int) number of calls made to the user's fQ function.

Return value

The return value flag (of type int) is one of:

CV_SUCCESS: The optional output value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.
CV_NO_QUAD: Quadrature integration has not been initialized.

Notes

CVodeGetQuadNumErrTestFails

Call

flag = CVodeGetQuadNumErrTestFails(cvode_mem, &nQetfails);

Description

The function CVodeGetQuadNumErrTestFails returns the number of local error test failures due to quadrature variables.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
nQetfails: (long int) number of error test failures due to quadrature variables.

Return value

The return value flag (of type int) is one of:

CV_SUCCESS: The optional output value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.
CV_NO_QUAD: Quadrature integration has not been initialized.

Notes

CVodeGetQuadErrWeights

Call

flag = CVodeGetQuadErrWeights(cvode_mem, eQweight);

Description

The function CVodeGetQuadErrWeights returns the quadrature error weights at the current time.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
eQweight: (N_Vector) quadrature error weights at the current time.

Return value

The return value flag (of type int) is one of:

CV_SUCCESS: The optional output value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.
CV_NO_QUAD: Quadrature integration has not been initialized.

Notes

The user must allocate memory for eQweight.

If quadratures were not included in the error control mechanism (through a call to CVodeSetQuadErrCon with errconQ = TRUE), CVodeGetQuadErrWeights does not set the eQweight vector.

CVodeGetQuadStats

Call

flag = CVodeGetQuadStats(cvode_mem, &nfQevals, &nQetfails);

Description

The function CVodeGetQuadStats returns the CVODES integrator statistics as a group.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
nfQevals: (long int) number of calls to the user's fQ function.
nQetfails: (long int) number of error test failures due to quadrature variables.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: the optional output values have been successfully set.
CV_MEM_NULL: the cvode_mem pointer is NULL.
CV_NO_QUAD: Quadrature integration has not been initialized.

Notes

5.7.6 User-supplied function for quadrature integration

For integration of quadrature equations, the user must provide a function that defines the right-hand side of the quadrature equations. This function must be of type CVQuadRhsFn defined as follows:

CVQuadRhsFn

Definition

	`typedef int (*CVQuadRhsFn)(`		`realtype t, N_Vector y,`
			`N_Vector yQdot, void *fQ_data);`

Purpose

This function computes the quadrature equation right-hand side for a given value of the independent variable t and state vector y.

Arguments

t: is the current value of the independent variable.
y: is the current value of the dependent variable vector, y(t).
yQdot: is the output vector f_Q(t, y).
fQ_data: is the fQ_data pointer passed to CVodeSetQuadFdata.

Return value

A CVQuadRhsFn should return 0 if successful, a positive value if a recoverable error occurred (in which case CVODES will attempt to correct), or a negative value if it failed unrecoverably (in which case the integration is halted and CV_QRHSFUNC_FAIL is returned).

Notes

Allocation of memory for yQdot is automatically handled within CVODES.

Both y and yQdot are of type N_Vector, but they typically have different internal representations. It is the user's responsibility to access the vector data consistently (including the use of the correct accessor macros from each NVECTOR implementation). For the sake of computational efficiency, the vector functions in the two NVECTOR implementations provided with CVODES do not perform any consistency checks with respect to their N_Vector arguments (see §8.1 and §8.2).

There are two situations in which recovery is not possible even if CVQuadRhsFn function returns a recoverable error flag. This include the situation when this occurrs at the very first call to the CVQuadRhsFn (in which case CVODES returns CV_FIRST_QRHSFUNC_ERR) or if a recoverable error is reported when CVQuadRhsFn is called after an error test failure, while the linear multistep method order is equal to 1 (in which case CVODES returns CV_UNREC_QRHSFUNC_ERR).

5.8 Rootfinding

While solving the IVP, CVODES has the capability to find the roots of a set of user-defined functions. This section describes the user-callable functions used to initialize and define the rootfinding problem and to obtain solution information, and it also describes the required user-supplied function.

5.8.1 User-callable functions for rootfinding

CVodeRootInit

Call

flag = CVodeRootInit(cvode_mem, nrtfn, g, g_data);

Description

The function CVodeRootInit specifies that the roots of a set of functions g_i(t, y) are to be found while the IVP is being solved.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block returned by CVodeCreate.
nrtfn: (int) is the number of root functions g_i.
g: (CVRootFn) is the C function which defines the nrtfn functions g_i(t, y) whose roots are sought. See §5.8.2 for details.
g_data: (void *) pointer to the user data for use by the user's root function g.

Return value

The return value flag (of type int) is one of

CV_SUCCESS: The call to CVodeRootInit was successful.
CV_MEM_NULL: The cvode_mem argument was NULL.
CV_MEM_FAIL: A memory allocation failed.
CV_ILL_INPUT: The function g is NULL, but nrtfn> 0.

Notes

If a new IVP is to be solved with a call to CVodeReInit, where the new IVP has no rootfinding problem but the prior one did, then call CVodeRootInit with nrtfn= 0.

There are two optional output functions associated with rootfinding.

CVodeGetRootInfo

Call

flag = CVodeGetRootInfo(cvode_mem, rootsfound);

Description

The function CVodeGetRootInfo returns an array showing which functions were found to have a root.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
rootsfound: (int *) an int array of length nrtfn showing the indices of the user functions g_i found to have a root. For i = 0,...,nrtfn-1, rootsfound[i]= 1 if g_i has a root, and 0 if not.

Return value

The return value flag (of type int) is one of:

CV_SUCCESS: The optional output values have been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.

Notes

The user must allocate memory for the vector rootsfound.

CVodeGetNumGEvals

Call

flag = CVodeGetNumGEvals(cvode_mem, &ngevals);

Description

The function CVodeGetNumGEvals returns the cumulative number of calls made to the user-supplied root function g.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
ngevals: (long int) number of calls made to the user's function g thus far.

Return value

The return value flag (of type int) is one of:

CV_SUCCESS: The optional output value has been successfully set.
CV_MEM_NULL: The cvode_mem pointer is NULL.

Notes

5.8.2 User-supplied function for rootfinding

If a rootfinding problem is to be solved during the integration of the ODE system, the user must supply a C function of type CVRootFn, defined as follows:

CVRootFn

Definition

	`typedef int (*CVRootFn)(`		`realtype t, N_Vector y, realtype *gout,`
			`void *g_data);`

Purpose

This function implements a vector-valued function g(t, y) such that the roots of the nrtfn components g_i(t, y) are sought.

Arguments

t: is the current value of the independent variable.
y: is the current value of the dependent variable vector, y(t).
gout: is the output array, of length nrtfn, with components g_i(t, y).
g_data: is the g_data pointer passed to CVodeRootInit.

Return value

A CVRootFn should return 0 if successful or a non-zero value if an error occured (in which case the integration is halted and CVode returns CV_RTFUNC_FAIL).

Notes

Allocation of memory for gout is automatically handled within CVODES.

5.9 Preconditioner modules

The efficiency of Krylov iterative methods for the solution of linear systems can be greatly enhanced through preconditioning. For problems in which the user cannot define a more effective, problem-specific preconditioner, CVODES provides a banded preconditioner in the module CVBANDPRE and a band-block-diagonal preconditioner module CVBBDPRE.

5.9.1 A serial banded preconditioner module

This preconditioner provides a band matrix preconditioner for use with any of the Krylov iterative linear solvers, in a serial setting. It uses difference quotients of the ODE right-hand side function f to generate a band matrix of bandwidth m_l + m_u + 1, where the number of super-diagonals (m_u, the upper half-bandwidth) and sub-diagonals (m_l, the lower half-bandwidth) are specified by the user, and uses this to form a preconditioner for use with the Krylov linear solver. Although this matrix is intended to approximate the Jacobian $\partial$ f / $\partial$ y, it may be a very crude approximation. The true Jacobian need not be banded, or its true bandwidth may be larger than m_l + m_u + 1, as long as the banded approximation generated here is sufficiently accurate to speed convergence as a preconditioner.

In order to use the CVBANDPRE module, the user need not define any additional functions. Aside from the header files required for the integration of the ODE problem (see §5.3), to use the CVBANDPRE module, the main program must include the header file cvodes_bandpre.h which declares the needed function prototypes. The following is a summary of the usage of this module. Steps that are unchanged from the skeleton program presented in §5.4 are grayed out.

Set problem dimensions
Set vector of initial values
Create CVODES object
Allocate internal memory
Set optional inputs
Initialize the CVBANDPRE preconditioner module
Specify the upper and lower half-bandwidths (mu and ml, respectively) and call
bp_data = CVBandPrecAlloc(cvode_mem, N, mu, ml);
to allocate memory for and to initialize a data structure (pointed to by bp_data) to be passed to the appropriate CVSp* linear solver.
Attach the Krylov linear solver, one of:
flag = CVBPSpgmr(cvode_mem, pretype, maxl, bp_data);
flag = CVBPSpbcg(cvode_mem, pretype, maxl, bp_data);
flag = CVBPSptfqmr(cvode_mem, pretype, maxl, bp_data);
Each function CVBPSp* is a wrapper around the corresponding specification function CVSp* and performs the following actions:
- Attaches the CVSPILS linear solver to the main CVODES solver memory;
- Sets the preconditioner data structure for CVBANDPRE;
- Sets the preconditioner setup function for CVBANDPRE;
- Sets the preconditioner solve function for CVBANDPRE;
The arguments pretype and maxl are described below. The last argument of CVBPSp* is the pointer to the CVBANDPRE data returned by CVBandPrecAlloc.
Set linear solver optional inputs
Note that the user should not overwrite the preconditioner data, setup function, or solve function through calls to CVSp* optional input functions.
Advance solution in time
Deallocate memory for solution vector
Free the CVBANDPRE data structure
CVBandPrecFree(&bp_data);
Free solver memory

The user-callable functions that initialize, attach, and deallocate the CVBANDPRE preconditioner module (steps 6, 7 and 11 above) are described in more detail below.

CVBandPrecAlloc

Call

bp_data = CVBandPrecAlloc(cvode_mem, N, mu, ml);

Description

The function CVBandPrecAlloc initializes and allocates memory for the CVBANDPRE preconditioner.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
N: (long int) problem dimension.
mu: (long int) upper half-bandwidth of the Jacobian approximation.
ml: (long int) lower half-bandwidth of the Jacobian approximation.

Return value

If successful, CVBandPrecAlloc returns a pointer to the newly created CVBANDPRE memory block (of type void *). If an error occurred, CVBandPrecAlloc returns NULL.

Notes

The banded approximate Jacobian will have nonzero elements only in locations (i, j) with -ml $\leq$ j - i $\leq$ mu.

CVBPSpgmr

Call

flag = CVBPSpgmr(cvode_mem, pretype, maxl, bp_data);

Description

The function CVBPSpgmr links the CVBANDPRE data to the CVSPGMR linear solver and attaches the latter to the CVODES memory block.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
pretype: (int) specifies the preconditioning type and must be either PREC_LEFT or PREC_RIGHT.
maxl: (int) maximum dimension of the Krylov subspace to be used. Pass 0 to use the default value CVSPILS_MAXL = 5.
bp_data: (void *) pointer to the CVBANDPRE data structure.

Return value

The return value flag (of type int) is one of:

CVSPILS_SUCCESS: The CVSPGMR initialization was successful.
CVSPILS_MEM_NULL: The cvode_mem pointer is NULL.
CVSPILS_ILL_INPUT: The preconditioner type pretype is not valid.
CVSPILS_MEM_FAIL: A memory allocation request failed.
CVBANDPRE_PDATA_NULL: The CVBANDPRE preconditioner has not been initialized.

Notes

CVBPSpbcg

Call

flag = CVBPSpbcg(cvode_mem, pretype, maxl, bp_data);

Description

The function CVBPSpbcg links the CVBANDPRE data to the CVSPBCG linear solver and attaches the latter to the CVODES memory block.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
pretype: (int) preconditioning type. Must be one of PREC_LEFT or PREC_RIGHT.
maxl: (int) maximum dimension of the Krylov subspace to be used. Pass 0 to use the default value CVSPILS_MAXL = 5.
bp_data: (void *) pointer to the CVBANDPRE data structure.

Return value

The return value flag (of type int) is one of

CVSPILS_SUCCESS: The CVSPBCG initialization was successful.
CVSPILS_MEM_NULL: The cvode_mem pointer is NULL.
CVSPILS_ILL_INPUT: The preconditioner type pretype is not valid.
CVSPILS_MEM_FAIL: A memory allocation request failed.
CVBANDPRE_PDATA_NULL: The CVBANDPRE preconditioner has not been initialized.

Notes

CVBPSptfqmr

Call

flag = CVBPSptfqmr(cvode_mem, pretype, maxl, bp_data);

Description

The function CVBPSptfqmr links the CVBANDPRE data to the CVSPTFQMR linear solver and attaches the latter to the CVODES memory block.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
pretype: (int) preconditioning type. Must be one of PREC_LEFT or PREC_RIGHT.
maxl: (int) maximum dimension of the Krylov subspace to be used. Pass 0 to use the default value CVSPILS_MAXL = 5.
bp_data: (void *) pointer to the CVBANDPRE data structure.

Return value

The return value flag (of type int) is one of

CVSPILS_SUCCESS: The CVSPTFQMR initialization was successful.
CVSPILS_MEM_NULL: The cvode_mem pointer is NULL.
CVSPILS_ILL_INPUT: The preconditioner type pretype is not valid.
CVSPILS_MEM_FAIL: A memory allocation request failed.
CVBANDPRE_PDATA_NULL: The CVBANDPRE preconditioner has not been initialized.

Notes

CVBandPrecFree
Call: CVBandPrecFree(&bp_data);
Description: The function CVBandPrecFree frees the pointer allocated by CVBandPrecAlloc.
Arguments: The only argument passed to CVBandPrecFree is the pointer to the CVBANDPRE data structure (of type void *).
Return value: The function CVBandPrecFree has no return value.
Notes

The following three optional output functions are available for use with the CVBANDPRE module:

CVBandPrecGetWorkSpace

Call

flag = CVBandPrecGetWorkSpace(bp_data, &lenrwBP, &leniwBP);

Description

The function CVBandPrecGetWorkSpace returns the sizes of the CVBANDPRE real and integer workspaces.

Arguments

bp_data: (void *) pointer to the CVBANDPRE data structure.
lenrwBP: (long int) the number of realtype values in the CVBANDPRE workspace.
leniwBP: (long int) the number of integer values in the CVBANDPRE workspace.

Return value

The return value flag (of type int) is one of:

CVBANDPRE_SUCCESS: The optional output values have been successfully set.
CVBANDPRE_PDATA_NULL: The CVBANDPRE preconditioner has not been initialized.

Notes

In terms of problem size N and smu = min(N - 1, mu+ml), the actual size of the real workspace is (2 ml + mu + smu +2) N realtype words, and the actual size of the integer workspace is N integer words.

The workspaces referred to here exist in addition to those given by the corresponding CVSp***GetWorkSpace function.

CVBandPrecGetNumRhsEvals

Call

flag = CVBandPrecGetNumRhsEvals(bp_data, &nfevalsBP);

Description

The function CVBandPrecGetNumRhsEvals returns the number of calls made to the user-supplied right-hand side function for finite difference banded Jacobian approximation used within the preconditioner setup function.

Arguments

bp_data: (void *) pointer to the CVBANDPRE data structure.
nfevalsBP: (long int) the number of calls to the user right-hand side function.

Return value

The return value flag (of type int) is one of:

CVBANDPRE_SUCCESS: The optional output value has been successfully set.
CVBANDPRE_PDATA_NULL: The CVBANDPRE preconditioner has not been initialized.

Notes

The counter nfevalsBP is distinct from the counter nfevalsLS returned by the corresponding CVSp***GetNumRhsEvals function, and also from nfevals, returned by CVodeGetNumRhsEvals. The total number of right-hand side function evaluations is the sum of all three of these counters.

CVBandPrecGetReturnFlagName
Call: name = CVBandPrecGetReturnFlagName(flag);
Description: The function CVBandPrecGetReturnFlagName returns the name of the CVBANDPRE constant corresponding to flag.
Arguments: The only argument, of type int is a return flag from a CVBANDPRE function.
Return value: The return value is a string containing the name of the corresponding constant.
Notes

5.9.2 A parallel band-block-diagonal preconditioner module

A principal reason for using a parallel ODE solver such as CVODES lies in the solution of partial differential equations (PDEs). Moreover, the use of a Krylov iterative method for the solution of many such problems is motivated by the nature of the underlying linear system of equations (3.5) that must be solved at each time step. The linear algebraic system is large, sparse and structured. However, if a Krylov iterative method is to be effective in this setting, then a nontrivial preconditioner needs to be used. Otherwise, the rate of convergence of the Krylov iterative method is usually unacceptably slow. Unfortunately, an effective preconditioner tends to be problem-specific.

However, we have developed one type of preconditioner that treats a rather broad class of PDE-based problems. It has been successfully used for several realistic, large-scale problems [20] and is included in a software module within the CVODES package. This module works with the parallel vector module NVECTOR-PARALLEL and is usable with any of the Krylov iterative linear solvers. It generates a preconditioner that is a block-diagonal matrix with each block being a band matrix. The blocks need not have the same number of super- and sub-diagonals and these numbers may vary from block to block. This Band-Block-Diagonal Preconditioner module is called CVBBDPRE.

One way to envision these preconditioners is to think of the domain of the computational PDE problem as being subdivided into M non-overlapping subdomains. Each of these subdomains is then assigned to one of the M processes to be used to solve the ODE system. The basic idea is to isolate the preconditioning so that it is local to each process, and also to use a (possibly cheaper) approximate right-hand side function. This requires the definition of a new function g(t, y) which approximates the function f (t, y) in the definition of the ODE system (3.1). However, the user may set g = f. Corresponding to the domain decomposition, there is a decomposition of the solution vector y into M disjoint blocks y_m, and a decomposition of g into blocks g_m. The block g_m depends both on y_m and on components of blocks y_m' associated with neighboring subdomains (so-called ghost-cell data). Let $\bar{{y}}_{m}^{}$ denote y_m augmented with those other components on which g_m depends. Then we have

g(t, y) = [g₁(t, $\displaystyle \bar{{y}}_{1}^{}$ ), g₂(t, $\displaystyle \bar{{y}}_{2}^{}$ ),..., g_M(t, $\displaystyle \bar{{y}}_{M}^{}$ )]^T

(5.1)

and each of the blocks g_m(t, $\bar{{y}}_{m}^{}$ ) is uncoupled from the others.

The preconditioner associated with this decomposition has the form

P = diag[P₁, P₂,..., P_M]

(5.2)

where

P_m $\displaystyle \approx$ I - $\displaystyle \gamma$ J_m

(5.3)

and J_m is a difference quotient approximation to $\partial$ g_m/ $\partial$ y_m. This matrix is taken to be banded, with upper and lower half-bandwidths mudq and mldq defined as the number of non-zero diagonals above and below the main diagonal, respectively. The difference quotient approximation is computed using mudq + mldq +2 evaluations of g_m, but only a matrix of bandwidth mu + ml +1 is retained. Neither pair of parameters need be the true half-bandwidths of the Jacobian of the local block of g, if smaller values provide a more efficient preconditioner. The solution of the complete linear system

Px = b

(5.4)

reduces to solving each of the equations

P_mx_m = b_m

(5.5)

and this is done by banded LU factorization of P_m followed by a banded backsolve.

Similar block-diagonal preconditioners could be considered with different treatments of the blocks P_m. For example, incomplete LU factorization or an iterative method could be used instead of banded LU factorization.

The CVBBDPRE module calls two user-provided functions to construct P: a required function gloc (of type CVLocalFn) which approximates the right-hand side function g(t, y) $\approx$ f (t, y) and which is computed locally, and an optional function cfn (of type CVCommFn) which performs all interprocess communication necessary to evaluate the approximate right-hand side g. These are in addition to the user-supplied right-hand side function f. Both functions take as input the same pointer f_data that is passed by the user to CVodeSetFdata and that was passed to the user's function f, and neither function has a return value. The user is responsible for providing space (presumably within f_data) for components of y that are communicated between processes by cfn, and that are then used by gloc, which is not expected to do any communication.

CVLocalFn

Definition

	`typedef int (*CVLocalFn)(`		`long int Nlocal, realtype t, N_Vector y,`
			`N_Vector glocal, void *f_data);`

Purpose

This function computes g(t, y). It loads the vector glocal as a function of t and y.

Arguments

Nlocal: is the local vector length.
t: is the value of the independent variable.
y: is the dependent variable.
glocal: is the output vector.
f_data: is the f_data pointer passed to CVodeSetFdata.

Return value

A CVLocalFn should return 0 if successful, a positive value if a recoverable error occurred (in which case CVODES will attempt to correct), or a negative value if it failed unrecoverably (in which case the integration is halted and CVode returns CV_LSETUP_FAIL).

Notes

This function assumes that all interprocess communication of data needed to calculate glocal has already been done, and that this data is accessible within f_data.

The case where g is mathematically identical to f is allowed.

CVCommFn

Definition

	`typedef int (*CVCommFn)(`		`long int Nlocal, realtype t,`
			`N_Vector y, void *f_data);`

Purpose

This function performs all interprocess communication necessary for the execution of the gloc function above, using the input vector y.

Arguments

Nlocal: is the local vector length.
t: is the value of the independent variable.
y: is the dependent variable.
f_data: is the f_data pointer passed to CVodeSetFdata.

Return value

A CVCommFn should return 0 if successful, a positive value if a recoverable error occurred (in which case CVODES will attempt to correct), or a negative value if it failed unrecoverably (in which case the integration is halted and CVode returns CV_LSETUP_FAIL).

Notes

The cfn function is expected to save communicated data in space defined within the data structure f_data.

Each call to the cfn function is preceded by a call to the right-hand side function f with the same (t, y) arguments. Thus, cfn can omit any communication done by f if relevant to the evaluation of glocal. If all necessary comunication was done in f, then cfn = NULL can be passed in the call to CVBBDPrecAlloc (see below).

Besides the header files required for the integration of the ODE problem (see §5.3), to use the CVBBDPRE module, the main program must include the header file cvodes_bbdpre.h which declares the needed function prototypes.

The following is a summary of the proper usage of this module. Steps that are unchanged from the skeleton program presented in §5.4 are grayed out.

Initialize MPI
Set problem dimensions
Set vector of initial values
Create CVODES object
Allocate internal memory
Set optional inputs
Initialize the CVBBDPRE preconditioner module
Specify the upper and lower half-bandwidths mudq and mldq, and mukeep and mlkeep, and call

bbd_data = CVBBDPrecAlloc( cvode_mem, local_N, mudq, mldq,

mukeep, mlkeep, dqrely, gloc, cfn);

to allocate memory for and to initialize a data structure bbd_data (of type void *) to be passed to the Krylov linear solver selected (in the next step). The last two arguments passed to CVBBDPrecAlloc are the two user-supplied functions described above.
Attach the Krylov linear solver, one of:
flag = CVBBDSpgmr(cvode_mem, pretype, maxl, bbd_data);
flag = CVBBDSpbcg(cvode_mem, pretype, maxl, bbd_data);
flag = CVBBDSptfqmr(cvode_mem, pretype, maxl, bbd_data);
The function CVBPSp* is a wrapper around the corresponding specification function CVSp* and performs the following actions:
- Attaches the CVSPILS linear solver to the main CVODES solver memory;
- Sets the preconditioner data structure for CVBBDPRE;
- Sets the preconditioner setup function for CVBBDPRE;
- Sets the preconditioner solve function for CVBBDPRE;
The arguments pretype and maxl are described below. The last argument of CVBBDSp* is the pointer to the CVBBDPRE data returned by CVBBDPrecAlloc.
Set linear solver optional inputs
Note that the user should not overwrite the preconditioner data, setup function, or solve function through calls to CVSPILS optional input functions.
Advance solution in time
Deallocate memory for solution vector
Free the CVBBDPRE data structure
CVBBDPrecFree(&bbd_data);
Free solver memory
Finalize MPI

The user-callable functions that initialize, attach, and deallocate the CVBBDPRE preconditioner module (steps 7, 8, and 12 above) are described next.

CVBBDPrecAlloc

Call

	`bbd_data = CVBBDPrecAlloc(`		`cvode_mem, local_N, mudq, mldq,`
			`mukeep, mlkeep, dqrely, gloc, cfn);`

Description

The function CVBBDPrecAlloc initializes and allocates memory for the CVBBDPRE preconditioner.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
local_N: (long int) local vector length.
mudq: (long int) upper half-bandwidth to be used in the difference quotient Jacobian approximation.
mldq: (long int) lower half-bandwidth to be used in the difference quotient Jacobian approximation.
mukeep: (long int) upper half-bandwidth of the retained banded approximate Jacobian block.
mlkeep: (long int) lower half-bandwidth of the retained banded approximate Jacobian block.
dqrely: (realtype) the relative increment in components of y used in the difference quotient approximations. The default is dqrely = $\sqrt{{\text{unit roundoff}}}$ , which can be specified by passing dqrely = 0.0.
gloc: (CVLocalFn) the C function which computes the approximation g(t, y) $\approx$ f (t, y).
cfn: (CVCommFn) the optional C function which performs all interprocess communication required for the computation of g(t, y).

Return value

If successful, CVBBDPrecAlloc returns a pointer to the newly created CVBBDPRE memory block (of type void *). If an error occurred, CVBBDPrecAlloc returns NULL.

Notes

If one of the half-bandwidths mudq or mldq to be used in the difference quotient calculation of the approximate Jacobian is negative or exceeds the value local_N-1, it is replaced with 0 or local_N-1 accordingly.

The half-bandwidths mudq and mldq need not be the true half-bandwidths of the Jacobian of the local block of g when smaller values may provide a greater efficiency.

Also, the half-bandwidths mukeep and mlkeep of the retained banded approximate Jacobian block may be even smaller, to reduce storage and computational costs further.

For all four half-bandwidths, the values need not be the same for every process.

CVBBDSpgmr

Call

flag = CVBBDSpgmr(cvode_mem, pretype, maxl, bbd_data);

Description

The function CVBBDSpgmr links the CVBBDPRE data to the CVSPGMR linear solver and attaches the latter to the CVODES memory block.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
pretype: (int) preconditioning type. Must be either PREC_LEFT or PREC_RIGHT.
maxl: (int) maximum dimension of the Krylov subspace to be used. Pass 0 to use the default value CVSPILS_MAXL = 5.
bbd_data: (void *) pointer to the CVBBDPRE data structure.

Return value

The return value flag (of type int) is one of:

CVSPILS_SUCCESS: The CVSPGMR initialization was successful.
CVSPILS_MEM_NULL: The cvode_mem pointer is NULL.
CVSPILS_ILL_INPUT: The preconditioner type pretype is not valid.
CVSPILS_MEM_FAIL: A memory allocation request failed.
CVBBDPRE_PDATA_NULL: The CVBBDPRE preconditioner has not been initialized.

Notes

CVBBDSpbcg

Call

flag = CVBBDSpbcg(cvode_mem, pretype, maxl, bbd_data);

Description

The function CVBBDSpbcg links the CVBBDPRE data to the CVSPBCG linear solver and attaches the latter to the CVODES memory block.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
pretype: (int) preconditioning type. Must be one of PREC_LEFT or PREC_RIGHT.
maxl: (int) maximum dimension of the Krylov subspace to be used. Pass 0 to use the default value CVSPILS_MAXL = 5.
bbd_data: (void *) pointer to the CVBBDPRE data structure.

Return value

The return value flag (of type int) is one of

CVSPILS_SUCCESS: The CVSPBCG initialization was successful.
CVSPILS_MEM_NULL: The cvode_mem pointer is NULL.
CVSPILS_ILL_INPUT: The preconditioner type pretype is not valid.
CVSPILS_MEM_FAIL: A memory allocation request failed.
CVBBDPRE_PDATA_NULL: The CVBBDPRE preconditioner has not been initialized.

Notes

CVBBDSptfqmr

Call

flag = CVBBDSptfqmr(cvode_mem, pretype, maxl, bbd_data);

Description

The function CVBBDSptfqmr links the CVBBDPRE data to the CVSPTFQMR linear solver and attaches the latter to the CVODES memory block.

Arguments

cvode_mem: (void *) pointer to the CVODES memory block.
pretype: (int) preconditioning type. Must be one of PREC_LEFT or PREC_RIGHT.
maxl: (int) maximum dimension of the Krylov subspace to be used. Pass 0 to use the default value CVSPILS_MAXL = 5.
bbd_data: (void *) pointer to the CVBBDPRE data structure.

Return value

The return value flag (of type int) is one of

CVSPILS_SUCCESS: The CVSPTFQMR initialization was successful.
CVSPILS_MEM_NULL: The cvode_mem pointer is NULL.
CVSPILS_ILL_INPUT: The preconditioner type pretype is not valid.
CVSPILS_MEM_FAIL: A memory allocation request failed.
CVBBDPRE_PDATA_NULL: The CVBBDPRE preconditioner has not been initialized.

Notes

CVBBDPrecFree
Call: CVBBDPrecFree(&bbd_data);
Description: The function CVBBDPrecFree frees the memory allocated by CVBBDPrecAlloc.
Arguments: The only argument passed to CVBBDPrecFree is the address of the pointer to the CVBBDPRE data structure (of type void *).
Return value: The function CVBBDPrecFree has no return value.
Notes

The CVBBDPRE module also provides a reinitialization function to allow solving a sequence of problems of the same size, with the same linear solver choice, provided there is no change in local_N, mukeep, or mlkeep. After solving one problem, and after calling CVodeReInit to re-initialize CVODES for a subsequent problem, a call to CVBBDPrecReInit can be made to change any of the following: the half-bandwidths mudq and mldq used in the difference-quotient Jacobian approximations, the relative increment dqrely, or one of the user-supplied functions gloc and cfn. If there is a change in any of the linear solver inputs, an additional call to CVSpgmr, CVSpbcg, or CVSptfqmr, and/or one or more of the corresponding CVSp***Set*** functions, must also be made.

CVBBDPrecReInit

Call

flag = CVBBDPrecReInit(bbd_data, mudq, mldq, dqrely, gloc, cfn);

Description

The function CVBBDPrecReInit re-initializes the CVBBDPRE preconditioner.

Arguments

bbd_data: (void *) pointer to the CVBBDPRE data structure.
mudq: (long int) upper half-bandwidth to be used in the difference quotient Jacobian approximation.
mldq: (long int) lower half-bandwidth to be used in the difference quotient Jacobian approximation.
dqrely: (realtype) the relative increment in components of y used in the difference quotient approximations. The default is dqrely = $\sqrt{{\text{unit roundoff}}}$ , which can be specified by passing dqrely = 0.0.
gloc: (CVLocalFn) the C function which computes the approximation g(t, y) $\approx$ f (t, y).
cfn: (CVCommFn) the optional C function which performs all interprocess communication required for the computation of g(t, y).

Return value

The return value flag (of type int) is one of

CVBBDPRE_SUCCESS: The CVSPBCG re-initialization was successful.
CVBBDPRE_PDATA_NULL: The CVBBDPRE preconditioner has not been initialized.

Notes

If one of the half-bandwidths mudq or mldq is negative or exceeds the value local_N-1, it is replaced with 0 or local_N-1 accordingly.

The following two optional output functions are available for use with the CVBBDPRE module:

CVBBDPrecGetWorkSpace

Call

flag = CVBBDPrecGetWorkSpace(bbd_data, &lenrwBBDP, &leniwBBDP);

Description

The function CVBBDPrecGetWorkSpace returns the local CVBBDPRE real and integer workspace sizes.

Arguments

bbd_data: (void *) pointer to the CVBBDPRE data structure.
lenrwBBDP: (long int) local number of realtype values in the CVBBDPRE workspace.
leniwBBDP: (long int) local number of integer values in the CVBBDPRE workspace.

Return value

The return value flag (of type int) is one of:

CVBBDPRE_SUCCESS: The optional output values have been successfully set.
CVBBDPRE_PDATA_NULL: The CVBBDPRE preconditioner has not been initialized.

Notes

In terms of local_N and smu = min(local_N - 1, mukeep + mlkeep), the actual size of the real workspace is (2 mlkeep + mukeep + smu +2) local_N realtype words, and the actual size of the integer workspace is local_N integer words. These values are local to each process.

The workspaces referred to here exist in addition to those given by the corresponding CVSp***GetWorkSpace function.

CVBBDPrecGetNumGfnEvals

Call

flag = CVBBDPrecGetNumGfnEvals(bbd_data, &ngevalsBBDP);

Description

The function CVBBDPrecGetNumGfnEvals returns the number of calls made to the user-supplied gloc function due to the finite difference approximation of the Jacobian blocks used within the preconditioner setup function.

Arguments

bbd_data: (void *) pointer to the CVBBDPRE data structure.
ngevalsBBDP: (long int) the number of calls made to the user-supplied gloc function.

Return value

The return value flag (of type int) is one of

CVBBDPRE_SUCCESS: The optional output value has been successfully set.
CVBBDPRE_PDATA_NULL: The CVBBDPRE preconditioner has not been initialized.

Notes

CVBBDPrecGetReturnFlagName
Call: name = CVBBDPrecGetReturnFlagName(flag);
Description: The function CVBBDPrecGetReturnFlagName returns the name of the CVBBDPRE constant corresponding to flag.
Arguments: The only argument, of type int is a return flag from a CVBBDPRE function.
Return value: The return value is a string containing the name of the corresponding constant.
Notes

In addition to the ngevalsBBDP gloc evaluations, the costs associated with CVBBDPRE also include nlinsetups LU factorizations, nlinsetups calls to cfn, npsolves banded backsolve calls, and nfevalsLS right-hand side function evaluations, where nlinsetups is an optional CVODES output and npsolves and nfevalsLS are linear solver optional outputs (see §5.5.7).

Next: 6. Using CVODES for Up: User Documentation for CVODES Previous: 4. Code Organization Contents Index

Radu Serban 2006-11-06