The FCVODE interface module is a package of C functions which support the use of the CVODE solver, for the solution of ODE systems dy/dt = f (t, y), in a mixed FORTRAN/C setting. While CVODE is written in C, it is assumed here that the user's calling program and user-supplied problem-defining routines are written in FORTRAN. This package provides the necessary interface to CVODE for both the serial and the parallel NVECTOR implementations.
The user-callable functions, with the corresponding CVODE functions, are as follows:
The user-supplied functions, each listed with the corresponding interface function which calls it (and its type within CVODE), are as follows:
| FCVODE routine (FORTRAN) | CVODE function (C) | CVODE function type |
| FCVFUN | FCVf | CVRhsFn |
| FCVEWT | FCVEwtSet | CVEwtFn |
| FCVDJAC | FCVDenseJac | CVDenseJacFn |
| FCVBJAC | FCVBandJac | CVBandJacFn |
| FCVPSOL | FCVPSol | CVSpilsPrecSolveFn |
| FCVPSET | FCVPSet | CVSpilsPrecSetupFn |
| FCVJTIMES | FCVJtimes | CVSpilsJacTimesVecFn |
In this package, the names of the interface functions, and the names of the FORTRAN user routines called by them, appear as dummy names which are mapped to actual values by a series of definitions in the header files fcvode.h, fcvroot.h, fcvbp.h, and fcvbbd.h. By default, those mapping definitions depend in turn on the C macro F77_FUNC defined in the header file sundials_config.h by configure. However, the set of flags SUNDIALS_CASE_UPPER, SUNDIALS_CASE_LOWER, SUNDIALS_UNDERSCORE_NONE, SUNDIALS_UNDERSCORE_ONE, and SUNDIALS_UNDERSCORE_TWO can be explicitly defined in the header file sundials_config.h when configuring SUNDIALS via the options -with-f77underscore and -with-f77case to override the default behavior if necessary (see Chapter 2). Either way, the names into which the dummy names are mapped are in upper or lower case and have up to two underscores appended.
The user must also ensure that variables in the user FORTRAN code are declared in a manner consistent with their counterparts in CVODE. All real variables must be declared as REAL, DOUBLE PRECISION, or perhaps as REAL*n, where n denotes the number of bytes, depending on whether CVODE was built in single, double, or extended precision (see Chapter 2). Moreover, some of the FORTRAN integer variables must be declared as INTEGER*4 or INTEGER*8 according to the C type long int. These integer variables include: the array of integer optional outputs (IOUT), problem dimensions (NEQ, NLOCAL, NGLOBAL), Jacobian half-bandwidths (MU, ML, etc.), as well as the array of user integer data, IPAR. This is particularly important when using CVODE and the FCVODE package on 64-bit architectures.
The usage of FCVODE requires calls to six or seven interface functions, depending on the method options selected, and one or more user-supplied routines which define the problem to be solved. These function calls and user routines are summarized separately below. Some details are omitted, and the user is referred to the description of the corresponding CVODE functions for information on the arguments of any given user-callable interface routine, or of a given user-supplied function called by an interface function. The usage of FCVODE for rootfinding and with preconditioner modules is described in later subsections.
Steps marked with [S] in the instructions below apply to the serial NVECTOR implementation (NVECTOR-SERIAL) only, while those marked with [P] apply to NVECTOR-PARALLEL.
The user must in all cases supply the following FORTRAN routine
SUBROUTINE FCVFUN(T, Y, YDOT, IPAR, RPAR, IER)
DIMENSION Y(*), YDOT(*), IPAR(*), RPAR(*)
It must set the YDOT array to f (t, y), the right-hand side of the ODE
system, as function of T= t and the array Y= y.
The arrays IPAR (of integers) and RPAR (of reals) contain user data
and are the same as those passed to FCVMALLOC.
IER is an error return flag which should be set to 0 if successful, a positive
value if a recoverable error occurred (in which case CVODE will attempt to correct),
or a negative value if it failed unrecoverably (in which case the integration is
halted).
[S] To initialize the serial NVECTOR module, the user must make the following call:
CALL FNVINITS(KEY, NEQ, IER)
where
KEY is the solver id (KEY = 1 for CVODE),
NEQ is the size of vectors, and
IER is a return completion flag which is 0 on success and -1
if a failure occurred.
[P] To initialize the parallel vector module, the user must make the following call:
CALL FNVINITP(COMM, KEY, NLOCAL, NGLOBAL, IER)
in which the arguments are: COMM = MPI communicator,
KEY = 1, NLOCAL = the local size of
vectors on this processor, and NGLOBAL = the system size (and the global
size of all vectors, equal to the sum of all values of NLOCAL).
The return flag IER is set to 0 on a successful return and to -1
otherwise.
If the header file sundials_config.h defines
SUNDIALS_MPI_COMM_F2C to be 1 (meaning the MPI
implementation used to build SUNDIALS includes the
MPI_Comm_f2c function), then COMM can be any valid
MPI communicator. Otherwise, MPI_COMM_WORLD will be used, so
just pass an integer value as a placeholder.
To set various problem and solution parameters and allocate internal memory, make the following call:
| CALL FCVMALLOC( | T0, Y0, METH, ITMETH, IATOL, RTOL, ATOL, | ||||
| & | IOUT, ROUT, IPAR, RPAR, IER) |
Modifications to the user data arrays IPAR and RPAR inside a user-provided routine will be propagated to all subsequent calls to such routines.
The optional outputs associated with the main CVODE integrator are listed in Table 6.2.
As an alternative to providing tolerances in the call to FCVMALLOC, the user may provide a routine to compute the error weights used in the WRMS norm evaluations. If supplied, it must have the following form:
SUBROUTINE FCVEWT (Y, EWT, IPAR, RPAR, IER)
DIMENSION Y(*), EWT(*), IPAR(*), RPAR(*)
It must set the positive components of the error weight vector EWT for
the calculation of the WRMS norm of Y. On return, set
IER = 0 if FCVEWT was successful, and nonzero otherwise.
The arrays IPAR (of integers) and RPAR (of reals) contain user data
and are the same as those passed to FCVMALLOC.
If the FCVEWT routine is provided, then, following the call to FCVMALOC, the user must make the call:
CALL FCVEWTSET (FLAG, IER)
with FLAG 
0 to specify use of the user-supplied error weight routine.
The argument IER is an error return flag which is 0
for success or non-zero if an error occurred.
In the case of a stiff system, the implicit BDF method involves the solution
of linear systems related to the Jacobian
J = 
f /y
of the ODE system. CVODE presently includes six choices for the treatment
of these systems, and the user of FCVODE must call a routine with a
specific name to make the desired choice.
[S] Diagonal approximate Jacobian
This choice is appropriate when the Jacobian can be well approximated by a diagonal matrix. The user must make the call:
CALL FCVDIAG(IER)
IER is an error return flag set on 0 on success or -1 if a memory
failure occurred.
There is no additional user-supplied routine. Optional outputs specific
to the DIAG case listed in Table 6.2.
[S] Dense treatment of the linear system
CALL FCVDENSE(NEQ, IER)
where NEQ is the size of the ODE system.
The argument IER is an error return flag which is 0
for success , -1 if a memory allocation failure occurred, or -2 for illegal
input.
As an option when using the DENSE linear solver, the user may supply a
routine that computes a dense approximation of the system Jacobian
J = f /y. If supplied, it must have the following form:
SUBROUTINE FCVDJAC (NEQ, T, Y, FY, DJAC, H, IPAR, RPAR,
& WK1, WK2, WK3, IER)
DIMENSION Y(*), FY(*), DJAC(NEQ,*), IPAR(*), RPAR(*),
& WK1(*), WK2(*), WK3(*)
Typically this routine will use only NEQ, T, Y, and DJAC.
It must compute the Jacobian and store it columnwise in DJAC.
The input arguments T, Y, and FY contain the current
values of t, y, and f (t, y), respectively.
The arrays IPAR (of integers) and RPAR (of reals) contain user data
and are the same as those passed to FCVMALLOC.
The vectors WK1, WK2, and WK3
of length NEQ are provided as work space for use in FCVDJAC.
IER is an error return flag which should be set to 0 if successful,
a positive value if a recoverable error occurred (in which case CVODE will
attempt to correct), or a negative value if FCVDJAC failed unrecoverably
(in which case the integration is halted).
If the user's FCVDJAC uses difference quotient approximations, it may need to use the error weight array EWT and current stepsize H in the calculation of suitable increments. The array EWT can be obtained by calling FCVGETERRWEIGHTS using one of the work arrays as temporary storage for EWT. It may also need the unit roundoff, which can be obtained as the optional output ROUT(6), passed from the calling program to this routine using either RPAR or a common block.
If the FCVDJAC routine is provided, then, following the call to FCVDENSE, the user must make the call:
CALL FCVDENSESETJAC (FLAG, IER)
with FLAG 0 to specify use of the user-supplied Jacobian
approximation. The argument IER is an error return flag which is 0
for success or non-zero if an error occurred.
Optional outputs specific to the DENSE case are listed in Table 6.2.
[S] Band treatment of the linear system
CALL FCVBAND (NEQ, MU, ML, IER)
The arguments are: MU, the upper half-bandwidth; ML,
the lower half-bandwidth; and IER an error return flag which is
0 for success , -1 if a memory allocation failure occurred, or -2
in case an input has an illegal value.
As an option when using the BAND linear solver, the user may supply a
routine that computes a band approximation of the system Jacobian
J = f /y. If supplied, it must have the following form:
SUBROUTINE FCVBJAC(NEQ, MU, ML, MDIM, T, Y, FY, BJAC, H, IPAR, RPAR,
& WK1, WK2, WK3, IER)
DIMENSION Y(*), FY(*), BJAC(MDIM,*), IPAR(*), RPAR(*),
& WK1(*), WK2(*), WK3(*)
Typically this routine will use only NEQ, MU, ML, T,
Y, and BJAC.
It must load the MDIM by N array BJAC with the Jacobian matrix
at the current (t,y) in band form. Store in BJAC(k, j) the Jacobian
element Ji, j with
k = i - j + MU +1 (
k = 1 ...
ML + MU + 1) and
j = 1 ... N.
The input arguments T, Y, and FY contain the current
values of t, y, and f (t, y), respectively.
The arrays IPAR (of integers) and RPAR (of reals) contain user data
and are the same as those passed to FCVMALLOC.
The vectors WK1, WK2,
and WK3 of length NEQ are provided as work space for use in
FCVBJAC.
IER is an error return flag which should be set to 0 if successful,
a positive value if a recoverable error occurred (in which case CVODE will
attempt to correct), or a negative value if FCVBJAC failed unrecoverably
(in which case the integration is halted).
If the user's FCVBJAC uses difference quotient approximations, it may need to use the error weight array EWT and current stepsize H in the calculation of suitable increments. The array EWT can be obtained by calling FCVGETERRWEIGHTS using one of the work arrays as temporary storage for EWT. It may also need the unit roundoff, which can be obtained as the optional output ROUT(6), passed from the calling program to this routine using either RPAR or a common block.
If the FCVBJAC routine is provided, then, following the call to FCVBAND, the user must make the call:
CALL FCVBANDSETJAC(FLAG, IER)
with FLAG 0 to specify use of the user-supplied Jacobian approximation.
The argument IER is an error return flag which is 0
for success or non-zero if an error occurred.
Optional outputs specific to the BAND case are listed in Table 6.2.
[S][P] SPGMR treatment of the linear systems
For the Scaled Preconditioned GMRES solution of the linear systems, the user must make the call
CALL FCVSPGMR(IPRETYPE, IGSTYPE, MAXL, DELT, IER)
The arguments are as follows.
IPRETYPE specifies the preconditioner type:
0 for no preconditioning, 1 for left only, 2 for right only, or 3 for
both sides. IGSTYPE indicates the Gram-Schmidt process type:
1 for modified G-S or 2 for classical G-S.
MAXL is the maximum Krylov subspace dimension.
DELT is the linear convergence tolerance factor.
For all of the input arguments, a value of 0 or 0.0 indicates the default.
IER is an error return flag which is 0 to indicate success, -1
if a memory allocation failure occurred, or -2 to indicate an illegal input.
Optional outputs specific to the SPGMR case are listed in Table 6.2.
For descriptions of the relevant optional user-supplied routines, see User-supplied routines for SPGMR/SPBCG/SPTFQMR below.
[S][P] SPBCG treatment of the linear systems
For the Scaled Preconditioned Bi-CGStab solution of the linear systems, the user must make the call
CALL FCVSPBCG(IPRETYPE, MAXL, DELT, IER)
Its arguments are the same as those with the same names for FCVSPGMR.
Optional outputs specific to the SPBCG case are listed in Table 6.2.
For descriptions of the relevant optional user-supplied routines, see User-supplied routines for SPGMR/SPBCG/SPTFQMR below.
[S][P] SPTFQMR treatment of the linear systems
For the Scaled Preconditioned Transpose-Reee Quasi-Minimal Residual solution of the linear systems, the user must make the call
CALL FCVSPTFQMR(IPRETYPE, MAXL, DELT, IER)
Its arguments are the same as those with the same names for FCVSPGMR.
Optional outputs specific to the SPTFQMR case are listed in Table 6.2.
For descriptions of the relevant optional user-supplied routines, see below.
[S][P] Functions used by SPGMR/SPBCG/SPTFQMR
An optional user-supplied routine, FCVJTIMES (see below), can be provided for Jacobian-vector products. If it is, then, following the call to FCVSPGMR, FCVSPBCG, or FCVSPTFQMR, the user must make the call:
CALL FCVSPILSSETJAC(FLAG, IER)
with FLAG 0 to specify use of the user-supplied
Jacobian-times-vector approximation.
The argument IER is an error return flag which is 0
for success or non-zero if an error occurred.
If preconditioning is to be done (IPRETYPE 0), then the user must call
CALL FCVSPILSSETPREC(FLAG, IER)
with FLAG 0. The return flag IER is 0 if
successful, or negative if a memory error occurred.
In addition, the user program must include
preconditioner routines FCVPSOL and FCVPSET (see below).
[S][P] User-supplied routines for SPGMR/SPBCG/SPTFQMR
With treatment of the linear systems by any of the Krylov iterative solvers, there are three optional user-supplied routines -- FCVJTIMES, FCVPSOL, and FCVPSET. The specifications for these routines are given below.
As an option when using the SPGMR, SPBCG, or SPTFQMR linear solvers,
the user may supply a routine that computes the product of the system Jacobian
J = f /y
and a given vector v. If supplied, it must have the following form:
SUBROUTINE FCVJTIMES (V, FJV, T, Y, FY, H, IPAR, RPAR, WORK, IER)
DIMENSION V(*), FJV(*), Y(*), FY(*), IPAR(*), RPAR(*), WORK(*)
Typically this routine will use only NEQ, T, Y, V, and
FJV. It must compute the product vector Jv, where the vector v is
stored in V, and store the product in FJV.
The input arguments T, Y, and FY contain the current
values of t, y, and f (t, y), respectively. On return, set
IER = 0 if FCVJTIMES was successful, and nonzero otherwise.
The arrays IPAR (of integers) and RPAR (of reals) contain user data
and are the same as those passed to FCVMALLOC.
The vector WORK, of length NEQ, is
provided as work space for use in FCVJTIMES.
If preconditioning is to be included, the following routine must be supplied, for solution of the preconditioner linear system:
SUBROUTINE FCVPSOL(T, Y, FY, R, Z, GAMMA, DELTA, LR, IPAR, RPAR,
& WORK, IER)
DIMENSION Y(*), FY(*), R(*), Z(*), IPAR(*), RPAR(*), WORK(*)
It must solve the preconditioner linear system Pz = r, where r = R
is input, and store the solution z in Z. Here P is the left
preconditioner if LR=1 and the right preconditioner if LR=2.
The preconditioner (or the product of the left and right preconditioners
if both are nontrivial) should be an approximation to the matrix
I - 
J, where I is the identity matrix, J is the system Jacobian,
and = GAMMA.
The input arguments T, Y, and FY contain the current
values of t, y, and f (t, y), respectively.
On return, set IER = 0 if FCVPSOL was successful, set IER
positive if a recoverable error occurred, and set IER negative if a
non-recoverable error occurred.
The arrays IPAR (of integers) and RPAR (of reals) contain user data and are the same as those passed to FCVMALLOC. The argument WORK is a work array of length NEQ for use by this routine.
If the user's preconditioner requires that any Jacobian related data be evaluated or preprocessed, then the following routine can be used for the evaluation and preprocessing of the preconditioner:
SUBROUTINE FCVPSET(T, Y, FY, JOK, JCUR, GAMMA, H, IPAR, RPAR,
& WORK1, WORK2, WORK3, IER)
DIMENSION Y(*), FY(*), EWT(*), IPAR(*), RPAR(*),
& WORK1(*), WORK2(*), WORK3(*)
It must perform any evaluation of Jacobian-related data and preprocessing needed
for the solution of the preconditioner linear systems by FCVPSOL.
The input argument JOK allows for Jacobian data to be saved and reused:
If JOK = 0, this data should be recomputed from scratch. If JOK = 1,
a saved copy of it may be reused, and the preconditioner constructed from it.
The input arguments T, Y, and FY contain the current
values of t, y, and f (t, y), respectively.
On return, set JCUR = 1 if Jacobian data was computed, and set
JCUR = 0 otherwise.
Also on return, set IER = 0 if FCVPSET was successful, set IER
positive if a recoverable error occurred, and set IER negative if a
non-recoverable error occurred.
The arrays IPAR (of integers) and RPAR (of reals) contain user data and are the same as those passed to FCVMALLOC. The arguments WORK1, WORK2, WORK3 are work arrays of length NEQ for use by this routine.
If the user calls FCVSPILSSETPREC the routine FCVPSET must
be provided, even if it is not needed and must return IER=0.
Notes
= r - Pz of the system should be made
less than DELTA in weighted 
norm, i.e.
![$ \sqrt{{\sum(\rho_i * {\tt EWT}[i])^2}}$](img74.png){kind=small}
< DELTA.
Carrying out the integration is accomplished by making calls as follows:
CALL FCVODE(TOUT, T, Y, ITASK, IER)
The arguments are as follows.
TOUT specifies the next value of t at which a solution is desired (input).
T is the value of t reached by the solver on output.
Y is an array containing the computed solution on output.
ITASK is a task indicator and should be set to 1 for normal mode
(overshoot TOUT and interpolate), to 2 for one-step mode
(return after each internal step taken), to 3 for normal mode with
the additional tstop constraint, or to 4 for one-step mode
with the additional constraint tstop.
IER is a completion flag and will be set to a positive value upon
successful return or to a negative value if an error occurred. These values
correspond to the CVode returns (see §5.5.4 and §10.2).
The current values of the optional outputs are available in IOUT and
ROUT (see Table 6.2).
To obtain a derivative of the solution, of order up to the current method order, make the following call:
CALL FCVDKY(T, K, DKY, IER)
where
T is the value of t at which solution derivative is desired, and
K is the derivative order (0
K QU).
On return, DKY is an array containing the computed K-th derivative
of y. The value T must lie between TCUR - HU and TCUR.
The return flag IER is set to 0 upon successful return or to a negative
value to indicate an illegal input.
To re-initialize the CVODE solver for the solution of a new problem of the same size as one already solved, make the following call:
CALL FCVREINIT(T0, Y0, IATOL, RTOL, ATOL, IER)
The arguments have the same names and meanings as those of FCVMALLOC.
FCVREINIT performs the same initializations as
FCVMALLOC, but does no memory allocation, using instead the existing
internal memory created by the previous FCVMALLOC call. The call to
specify the linear system solution method may or may not be needed.
Following this call, a call to specify the linear system solver must be made if the choice of linear solver is being changed. Otherwise, a call to reinitialize the linear solver last used may or may not be needed, depending on changes in the inputs to it.
In the case of the BAND solver, for any change in the half-bandwidths, call FCVBAND as described above.
In the case of SPGMR, for a change of inputs other than MAXL, make the call
CALL FCVSPGMRREINIT (IPRETYPE, IGSTYPE, DELT, IER)
which reinitializes SPGMR without reallocating its memory.
The arguments have the same names and meanings as those of FCVSPGMR.
If MAXL is being changed, then call FCVSPGMR instead.
In the case of SPBCG, for a change in any inputs, make the call
CALL FCVSPBCGREINIT (IPRETYPE, MAXL, DELT, IER)
which reinitializes SPBCG without reallocating its memory.
The arguments have the same names and meanings as those of FCVSPBCG.
In the case of SPTFQMR, for a change in any inputs, make the call
CALL FCVSPTFQMRREINIT (IPRETYPE, MAXL, DELT, IER)
which reinitializes SPTFQMR without reallocating its memory.
The arguments have the same names and meanings as those of FCVSPTFQMR.
To free the internal memory created by the call to FCVMALLOC, make the call
CALL FCVFREE
In order to keep the number of user-callable FCVODE interface routines to a minimum, optional inputs to the CVODE solver are passed through only two routines: FCVSETIIN for integer optional inputs and FCVSETRIN for real optional inputs. These functions should be called as follows:
CALL FCVSETIIN(KEY, IVAL, IER)
CALL FCVSETRIN(KEY, RVAL, IER)
where KEY is a quoted string indicating which optoinal input is set
(see Table 6.1),
IVAL is the integer input value to be used,
RVAL is the real input value to be used, and
IER is an integer return flag which is set to 0 on success and
a negative value if a failure occurred.
The optional outputs from the CVODE solver are accessed not through individual functions, but rather through a pair of arrays, IOUT (integer type) of dimension at least 21, and ROUT (real type) of dimension at least 6. These arrays are owned (and allocated) by the user and are passed as arguments to FCVMALLOC. Table 6.2 lists the entries in these two arrays and specifies the optional variable as well as the CVODE function which is actually called to extract the optional output.
For more details on the optional inputs and outputs, see §5.5.5 and §5.5.7.
In addition to the optional inputs communicated through FCVSET* calls and the optional outputs extracted from IOUT and ROUT, the following user-callable routines are available:
To obtain the error weight array EWT, containing the multiplicative error weights used the WRMS norms, make the following call:
CALL FCVGETERRWEIGHTS (EWT, IER)
This computes the EWT array normally defined by Eq. (3.6).
The array EWT, of length NEQ or NLOCAL, must already have been
declared by the user. The error return flag IER is zero if successful,
and negative if there was a memory error.
To obtain the estimated local errors, following a successful call to FCVSOLVE, make the following call:
CALL FCVGETESTLOCALERR (ELE, IER)
This computes the ELE array of estimated local errors as of the last
step taken. The array ELE must already have been declared by the user.
The error return flag IER is zero if successful, and negative if there
was a memory error.
The FCVROOT interface package allows programs written in FORTRAN to use the rootfinding feature of the CVODE solver module. The user-callable functions in FCVROOT, with the corresponding CVODE functions, are as follows:
CALL FCVROOTINIT (NRTFN, IER)
The arguments are as follows:
NRTFN is the number of root functions.
IER is a return completion flag; its values are 0 for success, -1
if the CVODE memory was NULL, and -11 if a memory allocation failed.
To specifiy the functions whose roots are to be found, the user must define the following routine:
SUBROUTINE FCVROOTFN (T, Y, G, IPAR, RPAR, IER)
DIMENSION Y(*), G(*), IPAR(*), RPAR(*)
It must set the G array, of length NRTFN, with components gi(t, y),
as a function of T = t and the array Y = y.
The arrays IPAR (of integers) and RPAR (of reals) contain user data
and are the same as those passed to FCVMALLOC.
Set IER on 0 if successful, or on a non-zero value if an error occurred.
When making calls to FCVODE to solve the ODE system, the occurrence of a root is flagged by the return value IER = 2. In that case, if NRTFN > 1, the functions gi which were found to have a root can be identified by making the following call:
CALL FCVROOTINFO (NRTFN, INFO, IER)
The arguments are as follows: NRTFN is the number of root functions.
INFO is an integer array of length NRTFN with root information.
IER is a return completion flag; its values are 0 for success,
negative if there was a memory failure. The returned values of INFO(i)
(i
= 1,..., NRTFN) are 0 or 1, such that INFO(i) = 1
if
g
was found to have a root, and INFO(i) = 0 otherwise.
The total number of calls made to the root function FCVROOTFN, denoted NGE, can be obtained from IOUT(12). If the FCVODE/CVODE memory block is reinitialized to solve a different problem via a call to FCVREINIT, then the counter NGE is reset to zero.
To free the memory resources allocated by a prior call to FCVROOTINIT make the following call:
CALL FCVROOTFREE
See §5.7 for additional information on the
rootfinding feature.
The FCVBP interface sub-module is a package of C functions which, as part of the FCVODE interface module, support the use of the CVODE solver with the serial NVECTOR-SERIAL module, and the combination of the CVBANDPRE preconditioner module (see §5.8.1) with any of the Krylov iterative linear solvers.
The user-callable functions in this package, with the corresponding CVODE and CVBANDPRE functions, are as follows:
As with the rest of the FCVODE routines, the names of the user-supplied routines are mapped to actual values through a series of definitions in the header file fcvbp.h.
The following is a summary of the usage of this module. Steps that are unchanged from the main program described in §6.2 are grayed-out.
To initialize the CVBANDPRE preconditioner, make the following call:
CALL FCVBPINIT(NEQ, MU, ML, IER)
The arguments are as follows.
NEQ is the problem size.
MU and ML are the upper and lower half-bandwidths of the band matrix
that is retained as an approximation of the Jacobian.
IER is a return completion flag. A value of 0 indicates success, while
a value of -1 indicates that a memory failure occurred.
To specify the SPGMR linear system solver and use the CVBANDPRE preconditioner, make the following call:
CALL FCVBPSPGMR(IPRETYPE, IGSTYPE, MAXL, DELT, IER)
Its arguments are the same as those of FCVSPGMR
(see step 4 in §6.2).
To specify the SPBCG linear system solver and use the CVBANDPRE preconditioner, make the following call:
CALL FCVBPSPBCG(IPRETYPE, MAXL, DELT, IER)
Its arguments are the same as those of FCVSPBCG
(see step 4 in §6.2).
To specify the SPBCG linear system solver and use the CVBANDPRE preconditioner, make the following call:
CALL FCVBPSPTFQMR(IPRETYPE, MAXL, DELT, IER)
Its arguments are the same as those of FCVSPTFQMR
(see step 4 in §6.2).
Optionally, to specify that SPGMR, SPBCG, or SPTFQMR should use the supplied FCVJTIMES, make the call
CALL FCVSPILSSETJAC(FLAG, IER)
with FLAG 0
(see step 4 in §6.2 for details).
Optional outputs specific to the SPGMR, SPBCG, or SPTFQMR solver are listed in Table 6.2. To obtain the optional outputs associated with the CVBANDPRE module, make the following call:
CALL FCVBPOPT(LENRWBP, LENIWBP, NFEBP)
The arguments returned are as follows.
LENRWBP is the length of real preconditioner work space, in realtype
words. LENIWBP is the length of integer preconditioner work space, in
integer words. NFEBP is the number of f (t, y) evaluations (calls to
FCVFUN) for difference-quotient banded Jacobian approximations.
To free the internal memory created by the call to FCVBPINIT, before calling FCVFREE, the user must make the call
CALL FCVBPFREE
The FCVBBD interface sub-module is a package of C functions which, as part of the FCVODE interface module, support the use of the CVODE solver with the parallel NVECTOR-PARALLEL module, and the combination of the CVBBDPRE preconditioner module (see §5.8.2) with any of the Krylov iterative linear solvers.
The user-callable functions in this package, with the corresponding CVODE and CVBBDPRE functions, are as follows:
In addition to the FORTRAN right-hand side function FCVFUN, the user-supplied functions used by this package, are listed below, each with the corresponding interface function which calls it (and its type within CVBBDPRE or CVODE):
| FCVBBD routine (FORTRAN) | CVODE function (C) | CVODE function type |
| FCVLOCFN | FCVgloc | CVLocalFn |
| FCVCOMMF | FCVcfn | CVCommFn |
| FCVJTIMES | FCVJtimes | CVSpilsJacTimesVecFn |
The following is a summary of the usage of this module. Steps that are unchanged from the main program described in §6.2 are grayed-out.
To initialize the CVBBDPRE preconditioner, make the following call:
CALL FCVBBDINIT(NLOCAL, MUDQ, MLDQ, MU, ML, DQRELY, IER)
The arguments are as follows.
NLOCAL is the local size of vectors on this processor.
MUDQ and MLDQ are the upper and lower half-bandwidths to be used in
the computation of the local Jacobian blocks by difference quotients.
These may be smaller than the true half-bandwidths of the
Jacobian of the local block of g, when smaller values may
provide greater efficiency.
MU and ML are the upper and lower half-bandwidths of the band matrix
that is retained as an approximation of the local Jacobian block.
These may be smaller than MUDQ and MLDQ.
DQRELY is the relative increment factor in y for difference quotients
(optional). A value of 0.0 indicates the default,
.
IER is a return completion flag. A value of 0 indicates success, while
a value of -1 indicates that a memory failure occurred or that an input had
an illegal value.
To specify the SPGMR linear system solver and use the CVBBDPRE preconditioner, make the following call:
CALL FCVBBDSPGMR(IPRETYPE, IGSTYPE, MAXL, DELT, IER)
Its arguments are the same as those of FCVSPGMR
(see step 4 in §6.2).
To specify the SPBCG linear system solver and use the CVBBDPRE preconditioner, make the following call:
CALL FCVBBDSPBCG(IPRETYPE, MAXL, DELT, IER)
Its arguments are the same as those of FCVSPBCG
(see step 4 in §6.2).
To specify the SPTFQMR linear system solver and use the CVBBDPRE preconditioner, make the following call:
CALL FCVBBDSPTFQMR(IPRETYPE, MAXL, DELT, IER)
Its arguments are the same as those of FCVSPTFQMR
(see step 4 in §6.2).
Optionally, to specify that SPGMR, SPBCG, or SPTFQMR should use the supplied FCVJTIMES, make the call
CALL FCVSPILSSETJAC(FLAG, IER)
with FLAG 0
(see step 4 in §6.2 for details).
Optional outputs specific to the SPGMR, SPBCG, or SPTFQMR solver are listed in Table 6.2. To obtain the optional outputs associated with the CVBBDPRE module, make the following call:
CALL FCVBBDOPT(LENRWBBD, LENIWBBD, NGEBBD)
The arguments returned are as follows.
LENRWBBD is the length of real preconditioner work space, in realtype
words. LENIWBBD is the length of integer preconditioner work space, in
integer words. These sizes are local to the current processor.
NGEBBD is the number of g(t, y) evaluations (calls to FCVLOCFN) so far.
If a sequence of problems of the same size is being solved using the same linear solver (SPGMR, SPBCG, or SPTFQMR) in combination with the CVBBDPRE preconditioner, then the CVODE package can be re-initialized for the second and subsequent problems by calling FCVREINIT, following which a call to FCVBBDINIT may or may not be needed. If the input arguments are the same, no FCVBBDINIT call is needed. If there is a change in input arguments other than MU or ML, then the user program should make the call
CALL FCVBBDREINIT(NLOCAL, MUDQ, MLDQ, DQRELY, IER)
This reinitializes the CVBBDPRE preconditioner, but without
reallocating its memory. The arguments of the FCVBBDREINIT
routine have the same names and meanings as those of FCVBBDINIT.
If the value of MU or ML is being changed, then a call to
FCVBBDINIT must be made. Finally, if there is a change in any of the
linear solver inputs, then a call to FCVBBDSPGMR, FCVBBDSPBCG, or
FCVBBDSPTFQMR must be made; in this case the linear solver memory is
reallocated.
To free the internal memory created by the call to FCVBBDINIT, before calling FCVFREE, the user must make the call
CALL FCVBBDFREE
The following two routines must be supplied for use with the CVBBDPRE module:
SUBROUTINE FCVGLOCFN (NLOC, T, YLOC, GLOC, IPAR, RPAR, IER)
DIMENSION YLOC(*), GLOC(*), IPAR(*), RPAR(*)
This routine is to evaluate the function g(t, y) approximating f
(possibly identical to f), in terms of T = t, and the array
YLOC (of length NLOC), which is the sub-vector
of y local to this processor. The resulting (local) sub-vector
is to be stored in the array GLOC.
The arrays IPAR (of integers) and RPAR (of reals) contain user data
and are the same as those passed to FCVMALLOC.
IER is an error return flag which should be set to 0 if successful,
a positive value if a recoverable error occurred (in which case CVODE will
attempt to correct), or a negative value if FCVGLOCFN failed unrecoverably
(in which case the integration is halted).
SUBROUTINE FCVCOMMFN (NLOC, T, YLOC, IPAR, RPAR, IER)
DIMENSION YLOC(*), IPAR(*), RPAR(*)
This routine is to perform the inter-processor communication necessary
for the FCVGLOCFN routine.
Each call to FCVCOMMFN is preceded by a call to the right-hand side
routine FCVFUN with the same arguments T and YLOC.
The arrays IPAR (of integers) and RPAR (of reals) contain user data
and are the same as those passed to FCVMALLOC.
IER is an error return flag (currently not used; set IER=0).
Thus FCVCOMMFN can omit any communications done by FCVFUN if
relevant to the evaluation of GLOC.
IER is an error return flag which should be set to 0 if successful,
a positive value if a recoverable error occurred (in which case CVODE will
attempt to correct), or a negative value if FCVCOMMFN failed unrecoverably
(in which case the integration is halted).
The subroutine FCVCOMMFN must be supplied even if it is not needed
and must return IER=0.
Optionally, the user can supply a routine FCVJTIMES for the evaluation of Jacobian-vector products, as described above in step 4 in §6.2.