nitsol_mod Module

Dimension of the problem

Vector of length n, initial guess on input and final approximate solution on output

User-supplied subroutine for evaluating the function the zero of which is sought.

User-supplied subroutine for optionally evaluating $J\vec{v}$ or $P^{-1}\vec{v}$, where $J$ is the Jacobian of $f$ and $P$ is a right preconditioning operator. If neither analytic $J\vec{v}$ evaluations nor right preconditioning is used, this can be a dummy subroutine; if right preconditioning is used but not analytic $J\vec{v}$ evaluations, this need only evaluate $P^{-1}\vec{v}$.

Stopping tolerance of the f-norm

Stopping tolerance of the step-length

Array containing various user-specified inputs; see above

Array containing various outputs; see above

Work array with length depending on the solver used as follows:

GMRES

$n\times(\text{kdmax}+5)+\text{kdmax}\times(\text{kdmax}+3)$, where kdmax is the maximum Krylove subspace dimension, either the default value of 20 or another value specified by the user

BiCGSTAB

$11n$

TFQMR

$14n$

Parameter/work array passed to the f and jacv routines

Parameter/work array passed to the f and jacv routines

Termination flag. Values have the following meanings:

-k

illegal value in input(k)

0

normal termination: $||F|| < \text{ftol}$ or $||\text{step}|| < \text{stptol}$

1

nnimax nonlinar iterations reached without success

2

failure to evaluate $F$

3

in nitjv, $J\vec{v}$ failure

4

in nitjv, $P^{-1}\vec{v}$ failure

5

in nitdrv, insufficient initial model norm reduction for adequate progress. Note: This can occur for several reasons; examine itrmks on return from the Krylov solver for further information. (This will be printed out if $\text{iplvl}\ge 3$; see the discussion of optional common blocks below.)

6

in nitbt, failure to reach an acceptable step through backtracking

User-supplied function for calculating vector inner products. This has the same interace as the BLAS routine ddot. If the Euclidean inner product is desired then user can link to a local BLAS library and provide the name ddot to nitsol. dinpr must be declared as an external function that returns a double precision in the calling program.

User-supplied function for calculating vector norms. This has the same interface as the BLAS routine dnrm2; if the Euclidean norm is desired the user can link to a local BLAS library and provide the name dnrm2 to nitsol. dnorm must be declared as an external function that returns a double precision value in the calling program.

Dimension of the problem

Array of length n containing the current $x$ value

Array of length n containing current approximate solution

Vector of of length n containing trial step

Relative residual reduction factor

User-supplied subroutine for evaluating the function the zero of which is sought.

User-supplied subroutine for optionally evaluating $J\vec{v}$ or $P^{-1}\vec{v}$, where $J$ is the Jacobian of $f$ and $P$ is a right preconditioning operator. If neither analytic $J\vec{v}$ evaluations nor right preconditioning is used, this can be a dummy subroutine; if right preconditioning is used but not analytic $J\vec{v}$ evaluations, this need only evaluate $P^{-1}\vec{v}$.

Parameter/work array passed to the f and jacv routines

Parameter/work array passed to the f and jacv routines

Flag for determining method of $J\vec{v}$ evaluation. 0 (default) indicates finite-difference evaluation, while 1 indicates analytic evaluation.

Flag for right preconditioning. 0 indicates no preconditioning, while 1 inidcates right preconditioning.

Maximum allowable number of GMRES iterations

Residual update flag. On GMRES restarts, the residual can be updated using a linear combination (iresup == 0) or by direct evaluation (iresup == 1). The first is cheap (one n-vector saxpy) but may lose accuracy with extreme residual reduction; the second retains accuracy better but costs one $J\vec{v}$ product.

Order of the finite-difference formula (sometimes) used on GMRES restarts when $J\vec{v}$ products are evaluated using finite- differences. When ijacv = 0 on input to nitsol, ifdord is set to 1, 2, or 4 in nitsol; otherwise, it is irrelevant. When ijacv = 0 on input to this subroutine, the precise meaning is as follows:

With GMRES, ifdord matters only if iresup = 1, in which case
it determines the order of the finite-difference formula used in evaluating the initial residual at each GMRES restart
(default 2). If iresup = 1 and ijacv = 0 on input to this
subroutine, then ijacv is temporarily reset to -1 at each
restart below to force a finite-difference evaluation of order ifdord. NOTE: This only affects initial residuals at restarts; first-order differences are always used within each GMRES
cycle. Using higher-order differences at restarts only should give the same accuracy as if higher-order differences were
used throughout; see K. Turner and H. F. Walker, "Efficient
high accuracy solutions with GMRES(m)," SIAM J. Sci. Stat.
Comput., 13 (1992), pp. 815--825.

Number of function evaluations

Number of $J\vec{v}$ evaluations

Number of $P^{-1}\vec{v}$ evaluations

Number of linear iterations

Maximum Krylov subspace dimension; default 10.

kdmax + 1

Matrix for storage of Krylov basis in GMRES; on return, the residual vector is contained in the first column.

Matrix for storage of triangular matrix in GMRES.

Vector for storage of estimate of singular vector of rr with largest singular value.

Vector for storage of estimate of singular vector of rr with smallest singular value.

Vector containing right-hand side of triangular system and least-squares residual norm in GMRES.

Work array

GMRES residual norm on return

Inner-product routine, either user-supplied or BLAS ddot.

Norm routine, either user supplied or BLAS dnrm2.

Termination flag. Values have the following meanings:

0

normal termination: acceptable step found

1

$J\vec{v}$ failure in nitjv

2

$P^{-1}\vec{v}$ failure in nitjv

3

Acceptable step not found in iksmax GMRES iterations

4

Insignificant residual norm reduction of a cycle of kdmax steps (stagnation) before an acceptable step has been found.

5

Dangerous ill-conditioning detected before an acceptable step has been found.

Dimension of the problem

Array of length n containing the current $x$ value

Array of length n containing current approximate solution

Vector of of length n containing trial step

Relative residual reduction factor

User-supplied subroutine for evaluating the function the zero of which is sought.

User-supplied subroutine for optionally evaluating $J\vec{v}$ or $P^{-1}\vec{v}$, where $J$ is the Jacobian of $f$ and $P$ is a right preconditioning operator. If neither analytic $J\vec{v}$ evaluations nor right preconditioning is used, this can be a dummy subroutine; if right preconditioning is used but not analytic $J\vec{v}$ evaluations, this need only evaluate $P^{-1}\vec{v}$.

Parameter/work array passed to the f and jacv routines

Parameter/work array passed to the f and jacv routines

Flag for determining method of $J\vec{v}$ evaluation. 0 (default) indicates finite-difference evaluation, while 1 indicates analytic evaluation.

Flag for right preconditioning. 0 indicates no preconditioning, while 1 inidcates right preconditioning.

Maximum allowable number of TFQMR iterations

Order of the finite-difference formula used in TFQMR when J*v products are evaluated using finite-differences. When ijacv = 0 on input to nitsol, ifdord is set to 1, 2, or 4 in nitsol; otherwise, it is irrelevant. When ijacv = 0 on input to this subroutine, ifdord determines the order of the finite-difference formula used at each TFQMR iteration (default 1). In this case, ijacv is set to -1 below to signal to nitjv that the order of the finite-difference formula is to be determined by ifdord. The original value ijacv = 0 is restored on return.

Number of function evaluations

Number of $J\vec{v}$ evaluations

Number of $P^{-1}\vec{v}$ evaluations

Number of linear iterations

Residual vector (for the QMR process)

Residual vector (of the underlying CGS process)

'Shadow' residual vector used in bi-orthogonalization

Vector used in TFQMR

Vector used in TFQMR

Vector used in TFQMR

Vector used in TFQMR

Vector used in TFQMR

Vector used in TFQMR

Work vector, passed on to nitjv

Work vector, passed on to nitjv

TFQMR residual norm on return

Inner-product routine, either user-supplied or BLAS ddot.

Norm routine, either user supplied or BLAS dnrm2.

Termination flag. Values have the following meanings:

0

normal termination: acceptable step found

1

$J\vec{v}$ failure in nitjv

2

$P^{-1}\vec{v}$ failure in nitjv

3

Acceptable step not found in iksmax TFQMR iterations

4

TFQMR breakdown

5

Floating point error (the underlying CGS iteration has probably blown up)

Dimension of the problem

Array of length n containing the current $x$ value

Array of length n containing current approximate solution

Vector of of length n containing trial step

Relative residual reduction factor

User-supplied subroutine for evaluating the function the zero of which is sought.

User-supplied subroutine for optionally evaluating $J\vec{v}$ or $P^{-1}\vec{v}$, where $J$ is the Jacobian of $f$ and $P$ is a right preconditioning operator. If neither analytic $J\vec{v}$ evaluations nor right preconditioning is used, this can be a dummy subroutine; if right preconditioning is used but not analytic $J\vec{v}$ evaluations, this need only evaluate $P^{-1}\vec{v}$.

Parameter/work array passed to the f and jacv routines

Parameter/work array passed to the f and jacv routines

Flag for determining method of $J\vec{v}$ evaluation. 0 (default) indicates finite-difference evaluation, while 1 indicates analytic evaluation.

Flag for right preconditioning. 0 indicates no preconditioning, while 1 inidcates right preconditioning.

Maximum allowable number of BiCGSTAB iterations

Order of the finite-difference formula used in BiCGSTAB when J*v products are evaluated using finite-differences. When ijacv = 0 on input to nitsol, ifdord is set to 1, 2, or 4 in nitsol; otherwise, it is irrelevant. When ijacv = 0 on input to this subroutine, ifdord determines the order of the finite-difference formula used at each BiCGSTAB iteration (default 1). In this case, ijacv is set to -1 below to signal to nitjv that the order of the finite-difference formula is to be determined by ifdord. The original value ijacv = 0 is restored on return.

Number of function evaluations

Number of $J\vec{v}$ evaluations

Number of $P^{-1}\vec{v}$ evaluations

Number of linear iterations

Residual vector

$\tilde{r}$ vector used in BiCGSTAB

Vector used in BiCGSTAB

Vector used in BiCGSTAB

Vector used in BiCGSTAB

Vector used in BiCGSTAB

Work vector, passed on to nitjv

Work vector, passed on to nitjv

BiCGSTAB residual norm on return

Inner-product routine, either user-supplied or BLAS ddot.

Norm routine, either user supplied or BLAS dnrm2.

Termination flag. Values have the following meanings:

0

normal termination: acceptable step found

1

$J\vec{v}$ failure in nitjv

2

$P^{-1}\vec{v}$ failure in nitjv

3

Acceptable step not found in iksmax BiCGSTAB iterations

4

BiCGSTAB breakdown

The length of the vectors

The first input vector

The stride in memory between successive elements of x

The second input vector

The stride in memory between successive elements of y

The length of the array

The input vector

The stride in memory between consecutive elements of x

The vector to be multiplied

Array containing the current estimate of the independent variables in the linear system. This may not be needed, but is provided just in case.

Array containing the right hand side of the linear system. This may not be needed, but is provided just in case.

Parameter/work array

Parameter/work array

Indicates whether operation was completed succesfully

Dimension of the problem

Array of length n containing the current $x$ value

Array of length n containing f(xcur) on output

Parameter/work array

Parameter/work array

Termination flag. 0 means normal termination, 1 means failure to produce f(xcur)

Dimension of the problem

Array of length n containing the current $x$ value

Array of length n containing the current $f(x)$ value

Integer flag indicating which product is desired. 0 indicates $z = J\vec{v}$. 1 indicates $z = P^{-1}\vec{v}$.

An array of length n to be multiplied

An array of length n containing the desired product on output.

Parameter/work array

Parameter/work array

Termination flag. 0 indcates normal termination, 1 indicatesfailure to prodce $J\vec{v}$, and 2 indicates failure to produce $P^{-1}\vec{v}$