The FIDA interface module is a package of C functions which support the use of the IDA solver, for the solution of DAE systems, in a mixed FORTRAN/C setting. While IDA 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 IDA for both the serial and the parallel NVECTOR implementations.
The user-callable functions, with the corresponding IDA functions, are as follows:
The user-supplied functions, each listed with the corresponding interface function which calls it (and its type within IDA), are as follows:
| FIDA routine (FORTRAN) | IDA function (C) | IDA function type |
| FIDARESFUN | FIDAresfn | IDAResFn |
| FIDAEWT | FIDAEwtSet | IDAEwtFn |
| FIDADJAC | FIDADenseJac | IDADenseJacFn |
| FIDABJAC | FIDABandJac | IDABandJacFn |
| FIDAPSOL | FIDAPSol | IDASpilsPrecSolveFn |
| FIDAPSET | FIDAPSet | IDASpilsPrecSetupFn |
| FIDAJTIMES | FIDAJtimes | IDASpilsJacTimesVecFn |
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 fida.h, fidaroot.h, and fidabbd.h.
By default, those mapping definitions depend in turn on the C macros
F77_FUNC and 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 -with-f77underscore
and -with-f77case options 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 IDA. 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 IDA 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 IDA and the FIDA package on 64-bit architectures.
The usage of FIDA requires calls to five or more 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 IDA 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 FIDA for rootfinding, and usage of FIDA with preconditioner modules, are each described in later sections.
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 FIDARESFUN (T, Y, YP, R, IPAR, RPAR, IER)
DIMENSION Y(*), YP(*), R(*), IPAR(*), RPAR(*)
It must set the R array to F(t, y, y'), the residual function of the DAE
system, as a function of T = t and the arrays Y = y and
YP = y'.
The arrays IPAR (of integers) and RPAR (of reals) contain user data
and are the same as those passed to FIDAMALLOC.
It should return IER = 0 if it was successful,
IER = 1 if it had a recoverable failure, or
IER = -1 if it had a non-recoverable failure.
[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 IDA),
NEQ is the size of vectors, and
IER is a return flag, which is set to 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 all vectors on this processor, and
NGLOBAL = the system size (and the global size of 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 FIDAMALLOC( | T0, Y0, YP0, 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 IDA integrator are listed in Table 6.2.
As an alternative to providing tolerances in the call to FIDAMALLOC, 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 FIDAEWT (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 FIDAEWT 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 FIDAMALLOC.
If the FIDAEWT routine is provided, then, following the call to FIDAMALLOC, the user must make the call:
CALL FIDAEWTSET (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.
The variable-order, variable-coefficient BDF method used by IDA involves
the solution of linear systems related to the system Jacobian
J = 
F/y + 
F/y
.
See Eq. (3.4). IDA presently includes five choices for
the treatment of these systems, and the user of FIDA must call a routine with
a specific name to make the desired choice.
[S] Dense treatment of the linear system
CALL FIDADENSE (NEQ, IER)
where NEQ is the size of the DAE 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. If supplied,
it must have the following form:
SUBROUTINE FIDADJAC (NEQ, T, Y, YP, R, DJAC, CJ, EWT, H,
& IPAR, RPAR, WK1, WK2, WK3, IER)
DIMENSION Y(*), YP(*), R(*), EWT(*), DJAC(NEQ,*),
& IPAR(*), RPAR(*), WK1(*), WK2(*), WK3(*)
This routine must compute the Jacobian and store it columnwise in DJAC.
The vectors WK1, WK2, and WK3 of length NEQ are provided
as work space for use in FIDADJAC.
The input arguments T, Y, YP, R, and CJ are the
current values of t, y, y', F(t, y, y'), and , respectively.
The arrays IPAR (of integers) and RPAR (of reals) contain user data
and are the same as those passed to FIDAMALLOC.
If the user's FIDADJAC uses difference quotient approximations, it may need to use the error weight array EWT and current stepsize H in the calculation of suitable increments. 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 COMMON.
If the FIDADJAC routine is provided, then, following the call to FIDADENSE, the user must make the call:
CALL FIDADENSESETJAC (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 FIDABAND (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. If supplied, it must have the following form:
SUBROUTINE FIDABJAC(NEQ, MU, ML, MDIM, T, Y, YP, R, CJ, BJAC,
& EWT, H, IPAR, RPAR, WK1, WK2, WK3, IER)
DIMENSION Y(*), YP(*), R(*), EWT(*), BJAC(MDIM,*),
& IPAR(*), RPAR(*), WK1(*), WK2(*), WK3(*)
This routine must load the MDIM by NEQ array BJAC with the
Jacobian matrix at the current
(t, y, 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 vectors
WK1, WK2, and WK3 of length NEQ are provided as work space
for use in FIDABJAC.
The input arguments T, Y, YP, R, and CJ are the
current values of t, y, y', F(t, y, y'), and , respectively.
The arrays IPAR (of integers) and RPAR (of reals) contain user data
and are the same as those passed to FIDAMALLOC.
If the user's FIDABJAC uses difference quotient approximations, it may need to use the error weight array EWT and current stepsize H in the calculation of suitable increments. 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 COMMON.
If the FIDABJAC routine is provided, then, following the call to FIDABAND, the user must make the call:
CALL FIDABANDSETJAC (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 FIDASPGMR (MAXL, IGSTYPE, MAXRS, EPLIFAC, DQINCFAC, IER)
The arguments are as follows.
MAXL is the maximum Krylov subspace dimension.
IGSTYPE indicates the Gram-Schmidt process type: 1 for modified,
or 2 for classical.
MAXRS maximum number of restarts.
EPLIFAC is the linear convergence tolerance factor.
DQINCFAC is the optional increment factor used in the matrix-vector product
Jv.
For all 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 FIDASPBCG (MAXL, EPLIFAC, DQINCFAC, IER)
The arguments are as follows.
MAXL is the maximum Krylov subspace dimension.
EPLIFAC is the linear convergence tolerance factor.
DQINCFAC is the optional increment factor used in the matrix-vector product
Jv.
For all 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 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-Free Quasi-Minimal Residual solution of the linear systems, the user must make the call
CALL FIDASPTFQMR (MAXL, EPLIFAC, DQINCFAC, IER)
The arguments are as follows.
MAXL is the maximum Krylov subspace dimension.
EPLIFAC is the linear convergence tolerance factor.
DQINCFAC is the optional increment factor used in the matrix-vector product
Jv.
For all 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 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, FIDAJTIMES, can be provided for Jacobian-vector products. If it is, then, following the call to FIDASPGMR, FIDASPBCG, or FIDASPTFQMR, the user must make the call:
CALL FIDASPILSSETJAC (FLAG, IER)
with FLAG 0. The return flag IER is 0 if successful,
or negative if a memory error occurred.
If preconditioning is to be done, then the user must call
CALL FIDASPILSSETPREC (FLAG, IER)
with FLAG 0. The return flag IER is 0 if successful,
or negative if a memory error occurred. In addition, the user must
supply preconditioner routines FIDAPSET and FIDAPSOL.
[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 -- FIDAJTIMES, FIDAPSOL, and FIDAPSET. The specifications for these routines are given below.
As an option when using any of the Krylov iterative solvers, the user may
supply a routine that computes the product of the system Jacobian
J = F/y + F/y
and a given vector v. If supplied, it must have the following form:
SUBROUTINE FIDAJTIMES(T, Y, YP, R, V, FJV, CJ, EWT, H,
& IPAR, RPAR, WK1, WK2, IER)
DIMENSION Y(*), YP(*), R(*), V(*), FJV(*), EWT(*),
& IPAR(*), RPAR(*), WK1(*), WK2(*)
This routine must compute the product vector Jv, where the vector v is
stored in V, and store the product in FJV. On return, set
IER = 0 if FIDAJTIMES was successful, and nonzero otherwise.
The vectors W1K and WK2, of length NEQ, are
provided as work space for use in FIDAJTIMES.
The input arguments T, Y, YP, R, and CJ are the
current values of t, y, y', F(t, y, y'), and , respectively.
The arrays IPAR (of integers) and RPAR (of reals) contain user data
and are the same as those passed to FIDAMALLOC.
If the user's FIDAJTIMES uses difference quotient approximations, it may need to use the error weight array EWT and current stepsize H in the calculation of suitable increments. 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 COMMON.
If preconditioning is to be included, the following routine must be supplied, for solution of the preconditioner linear system:
SUBROUTINE FIDAPSOL(T, Y, YP, R, RV, ZV, CJ, DELTA, EWT,
& IPAR, RPAR, WK1, IER)
DIMENSION Y(*), YP(*), R(*), RV(*), ZV(*), EWT(*),
& IPAR(*), RPAR(*), WK1(*)
It must solve the preconditioner linear system Pz = r, where r = RV
is input, and store the solution z in ZV. Here P is the left
preconditioner if LR=1 and the right preconditioner if LR=2.
The input arguments T, Y, YP, R, and CJ are the
current values of t, y, y', F(t, y, y'), and , respectively.
On return, set IER = 0 if FIDAPSOL was successful, set IER
positive if a recoverable error occurred, and set IER negative if a
non-recoverable error occurred.
The arguments EWT and DELTA are input and provide the error weight
array and a scalar tolerance, respectively, for use by FIDAPSOL if it uses
an iterative method in its solution. In that case, the residual vector
= r - Pz of the system should be made less than DELTA in weighted
norm, i.e.
![$ \sqrt{{\sum(\rho_i * {\tt EWT}[i])^2}}$](img72.png){kind=small}
< DELTA.
The argument WK1 is a work array of length NEQ for use by this
routine.
The arrays IPAR (of integers) and RPAR (of reals) contain user data
and are the same as those passed to FIDAMALLOC.
If the user's preconditioner requires that any Jacobian-related data be evaluated or preprocessed, then the following routine is to be used for the evaluation and preprocessing of the preconditioner:
SUBROUTINE FIDAPSET(T, Y, YP, R, CJ, EWT, H,
& IPAR, RPAR, WK1, WK2, WK3, IER)
DIMENSION Y(*), YP(*), R(*), EWT(*),
& IPAR(*), RPAR(*), WK1(*), WK2(*), WK3(*)
It must perform any evaluation of Jacobian-related data and preprocessing needed
for the solution of the preconditioner linear systems by FIDAPSOL.
The input arguments T, Y, YP, R, and CJ are the
current values of t, y, y', F(t, y, y'), and , respectively.
On return, set IER = 0 if FIDAPSET 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 FIDAMALLOC.
If the user's FIDAPSET uses difference quotient approximations, it may need to use the error weight array EWT and current stepsize H in the calculation of suitable increments. 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 COMMON.
If the user calls FIDASPILSSETPREC,
the subroutine FIDAPSET must be provided, even if it is not needed and
must return IER=0.
Optionally, to correct the initial values y and/or y', make the call
CALL FIDACALCIC (ICOPT, TOUT1, IER)
(See §3.1 for details.) The arguments are as follows:
ICOPT is 1 for initializing the algebraic components of y and
differential components of y', or 2 for initializing all of y.
IER is an error return flag, which is 0 for success, or negative
for a failure (see IDACalcIC return values).
Carrying out the integration is accomplished by making calls as follows:
CALL FIDASOLVE (TOUT, T, Y, YP, 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 vector y on output.
YP is an array containing the computed solution vector y' 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 IDASolve returns (see §5.5.5 and §10.2).
The current values of the optional outputs are available in IOUT and
ROUT (see Table 6.2).
After a successful return from FIDASOLVE, the routine FIDAGETSOL may be called to get interpolated values of y and y' for any value of t in the last internal step taken by IDA.
CALL FIDAGETSOL (T, Y, YP, IER)
where
T is the input value of t at which solution derivative is desired, and
Y and YP are arrays containing the computed vectors y and y'
on return. The value T must lie between TCUR-HLAST 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 IDA solver for the solution of a new problem of the same size as one already solved, make the following call:
CALL FIDAREINIT (T0, Y0, YP0, IATOL, RTOL, ATOL, IER)
The arguments have the same names and meanings as those of FIDAMALLOC.
FIDAREINIT performs the same initializations as FIDAMALLOC, but
does no memory allocation, using instead the existing internal memory
created by the previous FIDAMALLOC call.
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 FIDABAND as described above.
In the case of SPGMR, for a change of inputs other than MAXL, make the call
CALL FIDASPGMRREINIT (IGSTYPE, MAXRS, EPLIFAC, DQINCFAC, IER)
which reinitializes SPGMR without reallocating its memory.
The arguments have the same names and meanings as those of FIDASPGMR.
If MAXL is being changed, then call FIDASPGMR.
In the case of SPBCG, for a change in any inputs, make the call
CALL FIDASPBCGREINIT (MAXL, EPLIFAC, DQINCFAC, IER)
which reinitializes SPBCG without reallocating its memory.
The arguments have the same names and meanings as those of FIDASPBCG.
In the case of SPTFQMR, for a change in any inputs, make the call
CALL FIDASPTFQMRREINIT (MAXL, EPLIFAC, DQINCFAC, IER)
which reinitializes SPTFQMR without reallocating its memory.
The arguments have the same names and meanings as those of FIDASPTFQMR.
To free the internal memory created by the call to FIDAMALLOC, make the call
CALL FIDAFREE
In order to keep the number of user-callable FIDA interface routines to a minimum, optional inputs to the IDA solver are passed through only three routines: FIDASETIIN for integer optional inputs, FIDASETRIN for real optional inputs, and FIDASETVIN for real vector (array) optional inputs. These functions should be called as follows:
CALL FIDASETIIN(KEY, IVAL, IER)
CALL FIDASETRIN(KEY, RVAL, IER)
CALL FIDASETVIN(KEY, VVAL, IER)
where KEY is a quoted string indicating which optoinal input is set
(see Table 6.1), IVAL is the input integer value,
RVAL is the input real value (scalar),
VVAL is the input real array, and
IER is an integer return flag which is set to 0 on success and
a negative value if a failure occurred.
When using FIDASETVIN to specify the variable types (KEY = 'ID_VEC') the components in the array VVAL must be 1.0 to indicate a differential variable, or 0.0 to indicate an algebraic variable. Note that this array is required only if FIDACALCIC is to be called with ICOPT = 1, or if algebraic variables are suppressed from the error test (indicated using FIDASETIIN with KEY = 'SUPPRESS_ALG'). When using FIDASETVIN to specify optional constraints on the solution vector (KEY = 'CONSTR_VEC') the components in the array VVAL should be one of -2.0, -1.0, 0.0, 1.0, or 2.0. See the description of IDASetConstraints (§5.5.6.1) for details.
The optional outputs from the IDA 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 FIDAMALLOC. Table 6.2 lists the entries in these two arrays and specifies the optional variable as well as the IDA function which is actually called to extract the optional output.
For more details on the optional inputs and outputs, see §5.5.6 and §5.5.8.
In addition to the optional inputs communicated through FIDASET* calls and the optional outputs extracted from IOUT and ROUT, the following user-callable routines are available:
To reset the tolerances at any time, make the following call:
CALL FIDATOLREINIT (IATOL, RTOL, ATOL, IER)
The tolerance arguments have the same names and meanings as those of
FIDAMALLOC. The error return flag IER is 0 if successful,
and negative if there was a memory failure or illegal input.
To obtain the error weight array EWT, containing the multiplicative error weights used the WRMS norms, make the following call:
CALL FIDAGETERRWEIGHTS (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 FIDASOLVE, make the following call:
CALL FIDAGETESTLOCALERR (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 FIDAROOT interface package allows programs written in FORTRAN to use the rootfinding feature of the IDA solver module. The user-callable functions in FIDAROOT, with the corresponding IDA functions, are as follows:
CALL FIDAROOTINIT (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 IDA memory was NULL, and -14 if a memory allocation failed.
To specifiy the functions whose roots are to be found, the user must define the following routine:
SUBROUTINE FIDAROOTFN (T, Y, YP, G, IPAR, RPAR, IER)
DIMENSION Y(*), YP(*), G(*), IPAR(*), RPAR(*)
It must set the G array, of length NRTFN, with components
gi(t, y, y'), as a function of T = t and the arrays Y = y
and YP = y'.
The arrays IPAR (of integers) and RPAR (of reals) contain user data
and are the same as those passed to FIDAMALLOC.
Set IER on 0 if successful, or on a non-zero value if an error occurred.
When making calls to FIDASOLVE to solve the DAE 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 FIDAROOTINFO (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 FIDAROOTFN, denoted NGE, can be obtained from IOUT(12). If the FIDA/IDA memory block is reinitialized to solve a different problem via a call to FIDAREINIT, then the counter NGE is reset to zero.
To free the memory resources allocated by a prior call to FIDAROOTINIT make the following call:
CALL FIDAROOTFREE
See §5.7 for additional information on the
rootfinding feature.
The FIDABBD interface sub-module is a package of C functions which, as part of the FIDA interface module, support the use of the IDA solver with the parallel NVECTOR-PARALLEL module, in a combination of any of the Krylov iterative solver modules with the IDABBDPRE preconditioner module (see §5.8).
The user-callable functions in this package, with the corresponding IDA and IDABBDPRE functions, are as follows:
In addition to the FORTRAN residual function FIDARESFUN, the user-supplied functions used by this package, are listed below, each with the corresponding interface function which calls it (and its type within IDABBDPRE or IDA):
| FIDABBD routine (FORTRAN) | IDA function (C) | IDA function type |
| FIDAGLOCFN | FIDAgloc | IDABBDLocalFn |
| FIDACOMMFN | FIDAcfn | IDABBDCommFn |
| FIDAJTIMES | FIDAJtimes | IDASpilsJacTimesVecFn |
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 IDABBDPRE preconditioner, make the following call:
CALL FIDABBDINIT (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 IDABBDPRE preconditioner, make the following call:
CALL FIDABBDSPGMR (MAXL, IGSTYPE, MAXRS, EPLIFAC, DQINCFAC, IER)
Its arguments are the same as those of FIDASPGMR
(see step 4 in §6.2).
To specify the SPBCG linear system solver and use the IDABBDPRE preconditioner, make the following call:
CALL FIDABBDSPBCG (MAXL, EPLIFAC, DQINCFAC, IER)
Its arguments are the same as those of FIDASPBCG
(see step 4 in §6.2).
To specify the SPTFQMR linear system solver and use the IDABBDPRE preconditioner, make the following call:
CALL FIDABBDSPTFQMR (MAXL, EPLIFAC, DQINCFAC, IER)
Its arguments are the same as those of FIDASPTFQMR
(see step 4 in §6.2).
Optionally, to specify that SPGMR, SPBCG, or SPTFQMR should use the supplied FIDAJTIMES, make the call
CALL FIDASPILSSETJAC (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 IDABBDPRE module, make the following call:
CALL FIDABBDOPT (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. Both of these sizes are local to the current processor.
NGEBBD is the number of G(t, y, y') evaluations (calls to FIDALOCFN)
so far.
If a sequence of problems of the same size is being solved using the SPGMR, SPBCG, or SPTFQMR linear solver in combination with the IDABBDPRE preconditioner, then the IDA package can be re-initialized for the second and subsequent problems by calling FIDAREINIT, following which a call to FIDABBDINIT may or may not be needed. If the input arguments are the same, no FIDABBDINIT call is needed. If there is a change in input arguments other than MU, ML, or MAXL, then the user program should make the call
CALL FIDABBDREINIT (NLOCAL, MUDQ, MLDQ, DQRELY, IER)
This reinitializes the IDABBDPRE preconditioner, but without
reallocating its memory. The arguments of the FIDABBDREINIT
routine have the same names and meanings as those of FIDABBDINIT.
If the value of MU or ML is being changed, then a call to
FIDABBDINIT must be made. Finally, if MAXL is being changed,
then a call to FIDABBDSPGMR, FIDABBDSPBCG, or FIDASPTFQMR
must be made; in this case the linear solver memory is reallocated.
To free the internal memory created by the call to FIDABBDINIT, before calling FIDAFREE, the user must call
CALL FIDABBDFREE
The following two routines must be supplied for use with the IDABBDPRE module:
SUBROUTINE FIDAGLOCFN (NLOC, T, YLOC, YPLOC, GLOC, IPAR, RPAR, IER)
DIMENSION YLOC(*), YPLOC(*), GLOC(*), IPAR(*), RPAR(*)
This routine is to evaluate the function G(t, y, y') approximating F
(possibly identical to F), in terms of T = t, and the arrays
YLOC and YPLOC (of length NLOC), which are the sub-vectors
of y and y' local to this processor. The resulting (local) sub-vector
is to be stored in the array GLOC. IER is a return flag that
should be set to 0 if successful, to 1 (for a recoverable error), or to
-1 (for a non-recoverable error).
The arrays IPAR (of integers) and RPAR (of reals) contain user data
and are the same as those passed to FIDAMALLOC.
SUBROUTINE FIDACOMMFN (NLOC, T, YLOC, YPLOC, IPAR, RPAR, IER)
DIMENSION YLOC(*), YPLOC(*), IPAR(*), RPAR(*)
This routine is to perform the inter-processor communication necessary
for the FIDAGLOCFN routine.
Each call to FIDACOMMFN is preceded by a call to the residual routine
FIDARESFUN with the same arguments T, YLOC, and YPLOC.
Thus FIDACOMMFN can omit any communications done by FIDARESFUN if
relevant to the evaluation of GLOC.
The arrays IPAR (of integers) and RPAR (of reals) contain user data
and are the same as those passed to FIDAMALLOC.
IER is a return flag that should be set to 0 if successful, to 1
(for a recoverable error), or to -1 (for a non-recoverable error).
The subroutine FIDACOMMFN must be supplied even if it is empty and it must
return IER=0.
Optionally, the user can supply a routine FIDAJTIMES for the evaluation of Jacobian-vector products, as described above in step 4 in §6.2.