NAG FL Interface
f11bef (real_gen_basic_solver)
1
Purpose
f11bef is an iterative solver for a real general (nonsymmetric) system of simultaneous linear equations;
f11bef is the second in a suite of three routines, where the first routine,
f11bdf, must be called prior to
f11bef to set up the suite, and the third routine in the suite,
f11bff, can be used to return additional information about the computation.
These routines are suitable for the solution of large sparse general (nonsymmetric) systems of equations.
2
Specification
Fortran Interface
Integer, Intent (In) 
:: 
lwork 
Integer, Intent (Inout) 
:: 
irevcm, ifail 
Real (Kind=nag_wp), Intent (In) 
:: 
wgt(*) 
Real (Kind=nag_wp), Intent (Inout) 
:: 
u(*), v(*), work(lwork) 

C Header Interface
#include <nag.h>
void 
f11bef_ (Integer *irevcm, double u[], double v[], const double wgt[], double work[], const Integer *lwork, Integer *ifail) 

C++ Header Interface
#include <nag.h> extern "C" {
void 
f11bef_ (Integer &irevcm, double u[], double v[], const double wgt[], double work[], const Integer &lwork, Integer &ifail) 
}

The routine may be called by the names f11bef or nagf_sparse_real_gen_basic_solver.
3
Description
f11bef solves the general (nonsymmetric) system of linear simultaneous equations
$Ax=b$ of order
$\mathit{n}$, where
$\mathit{n}$ is large and the coefficient matrix
$A$ is sparse, using one of four available methods: RGMRES, the preconditioned restarted generalized minimum residual method (see
Saad and Schultz (1986)); CGS, the preconditioned conjugate gradient squared method (see
Sonneveld (1989)); BiCGSTAB(
$\ell $), the biconjugate gradient stabilized method of order
$\ell $ (see
Van der Vorst (1989) and
Sleijpen and Fokkema (1993)); or TFQMR, the transposefree quasiminimal residual method (see
Freund and Nachtigal (1991) and
Freund (1993)).
For a general description of the methods employed you are referred to
Section 3 in
f11bdf.
f11bef can solve the system after the first routine in the suite,
f11bdf, has been called to initialize the computation and specify the method of solution. The third routine in the suite,
f11bff, can be used to return additional information generated by the computation, during monitoring steps and after
f11bef has completed its tasks.
f11bef uses
reverse communication, i.e., it returns repeatedly to the calling program with the argument
irevcm (see
Section 5) set to specified values which require the calling program to carry out one of the following tasks:

–compute the matrixvector product $v=Au$ or $v={A}^{\mathrm{T}}u$ (the four methods require the matrix transposevector product only if ${\Vert A\Vert}_{1}$ or ${\Vert A\Vert}_{\infty}$ is estimated internally by Higham's method (see Higham (1988)));

–solve the preconditioning equation $Mv=u$;

–notify the completion of the computation;

–allow the calling program to monitor the solution.
Through the argument
irevcm the calling program can cause immediate or tidy termination of the execution. On final exit, the last iterates of the solution and of the residual vectors of the original system of equations are returned.
Reverse communication has the following advantages.

1.Maximum flexibility in the representation and storage of sparse matrices: all matrix operations are performed outside the solver routine, thereby avoiding the need for a complicated interface with enough flexibility to cope with all types of storage schemes and sparsity patterns. This applies also to preconditioners.

2.Enhanced user interaction: you can closely monitor the progress of the solution and tidy or immediate termination can be requested. This is useful, for example, when alternative termination criteria are to be employed or in case of failure of the external routines used to perform matrix operations.
4
References
Freund R W (1993) A transposefree quasiminimal residual algorithm for nonHermitian linear systems SIAM J. Sci. Comput. 14 470–482
Freund R W and Nachtigal N (1991) QMR: a QuasiMinimal Residual Method for NonHermitian Linear Systems Numer. Math. 60 315–339
Higham N J (1988) FORTRAN codes for estimating the onenorm of a real or complex matrix, with applications to condition estimation ACM Trans. Math. Software 14 381–396
Saad Y and Schultz M (1986) GMRES: a generalized minimal residual algorithm for solving nonsymmetric linear systems SIAM J. Sci. Statist. Comput. 7 856–869
Sleijpen G L G and Fokkema D R (1993) BiCGSTAB$\left(\ell \right)$ for linear equations involving matrices with complex spectrum ETNA 1 11–32
Sonneveld P (1989) CGS, a fast Lanczostype solver for nonsymmetric linear systems SIAM J. Sci. Statist. Comput. 10 36–52
Van der Vorst H (1989) BiCGSTAB, a fast and smoothly converging variant of BiCG for the solution of nonsymmetric linear systems SIAM J. Sci. Statist. Comput. 13 631–644
5
Arguments
Note: this routine uses
reverse communication. Its use involves an initial entry, intermediate exits and reentries, and a final exit, as indicated by the argument
irevcm. Between intermediate exits and reentries,
all arguments other than irevcm and v must remain unchanged.

1:
$\mathbf{irevcm}$ – Integer
Input/Output

On initial entry: ${\mathbf{irevcm}}=0$, otherwise an error condition will be raised.
On intermediate reentry: must either be unchanged from its previous exit value, or can have one of the following values.
 ${\mathbf{irevcm}}=5$
 Tidy termination: the computation will terminate at the end of the current iteration. Further reverse communication exits may occur depending on when the termination request is issued. f11bef will then return with the termination code ${\mathbf{irevcm}}=4$. Note that before calling f11bef with ${\mathbf{irevcm}}=5$ the calling program must have performed the tasks required by the value of irevcm returned by the previous call to f11bef, otherwise subsequently returned values may be invalid.
 ${\mathbf{irevcm}}=6$
 Immediate termination: f11bef will return immediately with termination code ${\mathbf{irevcm}}=4$ and with any useful information available. This includes the last iterate of the solution. The residual vector is generally not available.
Immediate termination may be useful, for example, when errors are detected during matrixvector multiplication or during the solution of the preconditioning equation.
Changing
irevcm to any other value between calls will result in an error.
On intermediate exit:
has the following meanings.
 ${\mathbf{irevcm}}=1$
 The calling program must compute the matrixvector product $v={A}^{\mathrm{T}}u$, where $u$ and $v$ are stored in u and v, respectively; RGMRES, CGS and BiCGSTAB($\ell $) methods return ${\mathbf{irevcm}}=1$ only if the matrix norm ${\Vert A\Vert}_{1}$ or ${\Vert A\Vert}_{\infty}$ is estimated internally using Higham's method. This can only happen if ${\mathbf{iterm}}=1$ in f11bdf.
 ${\mathbf{irevcm}}=1$
 The calling program must compute the matrixvector product $v=Au$, where $u$ and $v$ are stored in u and v, respectively.
 ${\mathbf{irevcm}}=2$
 The calling program must solve the preconditioning equation $Mv=u$, where $u$ and $v$ are stored in u and v, respectively.
 ${\mathbf{irevcm}}=3$
 Monitoring step: the solution and residual at the current iteration are returned in the arrays u and v, respectively. No action by the calling program is required. f11bff can be called at this step to return additional information.
On final exit:
${\mathbf{irevcm}}=4$:
f11bef has completed its tasks. The value of
ifail determines whether the iteration has been successfully completed, errors have been detected or the calling program has requested termination.
Constraint:
on initial entry,
${\mathbf{irevcm}}=0$; on reentry, either
irevcm must remain unchanged or be reset to
$5$ or
$6$.
Note: any values you return to f11bef as part of the reverse communication procedure should not include floatingpoint NaN (Not a Number) or infinity values, since these are not handled by f11bef. If your code does inadvertently return any NaNs or infinities, f11bef is likely to produce unexpected results.

2:
$\mathbf{u}\left(*\right)$ – Real (Kind=nag_wp) array
Input/Output

Note: the dimension of the array
u
must be at least
$\mathit{n}$.
On initial entry: an initial estimate, ${x}_{0}$, of the solution of the system of equations $Ax=b$.
On intermediate reentry: must remain unchanged.
On intermediate exit:
the returned value of
irevcm determines the contents of
u in the following way:
 if ${\mathbf{irevcm}}=1$, $1$ or $2$, u holds the vector $u$ on which the operation specified by irevcm is to be carried out;
 if ${\mathbf{irevcm}}=3$, u holds the current iterate of the solution vector.
On final exit: if
${\mathbf{ifail}}={\mathbf{3}}$ or
${\mathbf{ifail}}<{\mathbf{0}}$, the array
u is unchanged from the initial entry to
f11bef.
If
${\mathbf{ifail}}={\mathbf{1}}$, the array
u is unchanged from the last entry to
f11bef.
Otherwise,
u holds the last available iterate of the solution of the system of equations, for all returned values of
ifail.

3:
$\mathbf{v}\left(*\right)$ – Real (Kind=nag_wp) array
Input/Output

Note: the dimension of the array
v
must be at least
$\mathit{n}$.
On initial entry: the righthand side $b$ of the system of equations $Ax=b$.
On intermediate reentry: the returned value of
irevcm determines the contents of
v in the following way:
 if ${\mathbf{irevcm}}=1$, $1$ or $2$, v must store the vector $v$, the result of the operation specified by the value of irevcm returned by the previous call to f11bef;
 if ${\mathbf{irevcm}}=3$, v must remain unchanged.
On intermediate exit:
if
${\mathbf{irevcm}}=3$,
v holds the current iterate of the residual vector. Note that this is an approximation to the true residual vector. Otherwise, it does not contain any useful information.
On final exit: if
${\mathbf{ifail}}={\mathbf{3}}$ or
${\mathbf{ifail}}<{\mathbf{0}}$, the array
v is unchanged from the initial entry to
f11bef.
If
${\mathbf{ifail}}={\mathbf{1}}$, the array
v is unchanged from the last entry to
f11bef.
If
${\mathbf{ifail}}={\mathbf{0}}$ or
${\mathbf{2}}$, the array
v contains the true residual vector of the system of equations (see also
Section 6).
Otherwise,
v stores the last available iterate of the residual vector unless
${\mathbf{ifail}}={\mathbf{8}}$ is returned on last entry, in which case
v is set to
$0.0$.

4:
$\mathbf{wgt}\left(*\right)$ – Real (Kind=nag_wp) array
Input

Note: the dimension of the array
wgt
must be at least
$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,\mathit{n}\right)$.
On entry: the usersupplied weights, if these are to be used in the computation of the vector norms in the termination criterion (see
Sections 3 and
5 in
f11bdf).
Constraint:
if weights are to be used, at least one element of
wgt must be nonzero.

5:
$\mathbf{work}\left({\mathbf{lwork}}\right)$ – Real (Kind=nag_wp) array
Communication Array

On initial entry: the array
work as returned by
f11bdf (see also
Section 5 in
f11bdf).
On intermediate reentry: must remain unchanged.

6:
$\mathbf{lwork}$ – Integer
Input

On initial entry: the dimension of the array
work as declared in the (sub)program from which
f11bef is called (see also
Sections 3 and
5 in
f11bdf).
The required amount of workspace is as follows:
Method 
Requirements 
RGMRES 
${\mathbf{lwork}}=100+\mathit{n}\left(m+3\right)+m\left(m+5\right)+1$, where $m$ is the dimension of the basis. 
CGS 
${\mathbf{lwork}}=100+7\mathit{n}$. 
BiCGSTAB($\ell $) 
${\mathbf{lwork}}=100+\left(2\mathit{n}+\ell \right)\left(\ell +2\right)+p$, where $\ell $ is the order of the method. 
TFQMR 
${\mathbf{lwork}}=100+10\mathit{n}$, 
where
$p=2\mathit{n}$ 
if $\ell >1$ and ${\mathbf{iterm}}=2$ was supplied. 
$p=\mathit{n}$ 
if $\ell >1$ and a preconditioner is used or ${\mathbf{iterm}}=2$ was supplied. 
$p=0$ 
otherwise. 
Constraint:
${\mathbf{lwork}}\ge {\mathbf{lwreq}}$, where
lwreq is returned by
f11bdf.

7:
$\mathbf{ifail}$ – Integer
Input/Output

On initial entry:
ifail must be set to
$0$,
$1$ or
$1$ to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $1$ means that an error message is printed while a value of $1$ means that it is not.
If halting is not appropriate, the value
$1$ or
$1$ is recommended. If message printing is undesirable, then the value
$1$ is recommended. Otherwise, the value
$1$ is recommended since useful values can be provided in some output arguments even when
${\mathbf{ifail}}\ne {\mathbf{0}}$ on exit.
When the value $\mathbf{1}$ or $\mathbf{1}$ is used it is essential to test the value of ifail on exit.
On final exit:
${\mathbf{ifail}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see
Section 6).
6
Error Indicators and Warnings
If on entry
${\mathbf{ifail}}=0$ or
$1$, explanatory error messages are output on the current error message unit (as defined by
x04aaf).
Errors or warnings detected by the routine:
 ${\mathbf{ifail}}=1$

f11bef has already completed its tasks. You need to set a new problem.
f11bef has been called again after returning the termination code
${\mathbf{irevcm}}=4$. No further computation has been carried out and all input data and data stored for access by
f11bff have remained unchanged.
 ${\mathbf{ifail}}=2$

The required accuracy could not be obtained. However, a reasonable accuracy may have been achieved.
Userrequested tidy termination. The required accuracy has not been achieved. However, a reasonable accuracy may have been achieved.
f11bef has terminated with reasonable accuracy: the last iterate of the residual satisfied the termination criterion but the exact residual
$r=bAx$, did not. After the first occurrence of this situation, the iteration was restarted once, but
f11bef could not improve on the accuracy. This error code usually implies that your problem has been fully and satisfactorily solved to within or close to the accuracy available on your system. Further iterations are unlikely to improve on this situation. You should call
f11bff to check the values of the left and righthand sides of the termination condition.
 ${\mathbf{ifail}}=3$

Either
f11bdf was not called before calling
f11bef or it has returned an error.
 ${\mathbf{ifail}}=4$

Userrequested tidy termination. The solution has not converged after $\u2329\mathit{\text{value}}\u232a$ iterations.
 ${\mathbf{ifail}}=5$

The solution has not converged after $\u2329\mathit{\text{value}}\u232a$ iterations.
 ${\mathbf{ifail}}=6$

Algorithm breakdown at iteration no. $\u2329\mathit{\text{value}}\u232a$.
The last available iterates of the solution and residuals are returned, although it is possible that they are completely inaccurate.
 ${\mathbf{ifail}}=8$

Userrequested immediate termination.
The array
u returns the last iterate of the solution, the array
v returns the last iterate of the residual vector, for the CGS and TFQMR methods only.
 ${\mathbf{ifail}}=10$

The weights in array
wgt are all zero.
 ${\mathbf{ifail}}=1$

On initial entry, ${\mathbf{irevcm}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{irevcm}}=0$.
On intermediate reentry,
${\mathbf{irevcm}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: either
irevcm must be unchanged from its previous exit value or
${\mathbf{irevcm}}=5$ or
$6$.
 ${\mathbf{ifail}}=6$

On entry,
${\mathbf{lwork}}=\u2329\mathit{\text{value}}\u232a$.
Constraint:
${\mathbf{lwork}}\ge {\mathbf{lwreq}}$, where
lwreq is returned by
f11bdf.
 ${\mathbf{ifail}}=99$
An unexpected error has been triggered by this routine. Please
contact
NAG.
See
Section 7 in the Introduction to the NAG Library FL Interface for further information.
 ${\mathbf{ifail}}=399$
Your licence key may have expired or may not have been installed correctly.
See
Section 8 in the Introduction to the NAG Library FL Interface for further information.
 ${\mathbf{ifail}}=999$
Dynamic memory allocation failed.
See
Section 9 in the Introduction to the NAG Library FL Interface for further information.
7
Accuracy
On completion, i.e.,
${\mathbf{irevcm}}=4$ on exit, the arrays
u and
v will return the solution and residual vectors,
${x}_{k}$ and
${r}_{k}=bA{x}_{k}$, respectively, at the
$k$th iteration, the last iteration performed, unless an immediate termination was requested.
On successful completion, the termination criterion is satisfied to within the userspecified tolerance, as described in
Section 3 in
f11bdf. The computed values of the left and righthand sides of the termination criterion selected can be obtained by a call to
f11bff.
8
Parallelism and Performance
f11bef is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
f11bef makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the
X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the
Users' Note for your implementation for any additional implementationspecific information.
The number of operations carried out by f11bef for each iteration is likely to be principally determined by the computation of the matrixvector products $v=Au$ and by the solution of the preconditioning equation $Mv=u$ in the calling program. Each of these operations is carried out once every iteration.
The number of the remaining operations in f11bef for each iteration is approximately proportional to $\mathit{n}$.
The number of iterations required to achieve a prescribed accuracy cannot be easily determined at the onset, as it can depend dramatically on the conditioning and spectrum of the preconditioned matrix of the coefficients $\overline{A}={M}^{1}A$ (RGMRES, CGS and TFQMR methods) or $\overline{A}=A{M}^{1}$ (BiCGSTAB($\ell $) method).
Additional matrixvector products are required for the computation of
${\Vert A\Vert}_{1}$ or
${\Vert A\Vert}_{\infty}$, when this has not been supplied to
f11bdf and is required by the termination criterion employed.
If the termination criterion
${\Vert {r}_{k}\Vert}_{p}\le \tau \left({\Vert b\Vert}_{p}+{\Vert A\Vert}_{p}\times {\Vert {x}_{k}\Vert}_{p}\right)$ is used (see
Section 3 in
f11bdf) and
$\Vert {x}_{0}\Vert \gg \Vert {x}_{k}\Vert $, then the required accuracy cannot be obtained due to loss of significant digits. The iteration is restarted automatically at some suitable point:
f11bef sets
${x}_{0}={x}_{k}$ and the computation begins again. For particularly badly scaled problems, more than one restart may be necessary. This does not apply to the RGMRES method which, by its own nature, selfrestarts every superiteration. Naturally, restarting adds to computational costs: it is recommended that the iteration should start from a value
${x}_{0}$ which is as close to the true solution
$\stackrel{~}{x}$ as can be estimated. Otherwise, the iteration should start from
${x}_{0}=0$.
10
Example
See
Section 10 in
f11bdf.