NAG FL Interface
f11gff (real_​symm_​basic_​diag)

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

1: $\mathbf{itn}$ – Integer Output

On exit: the number of iterations carried out by f11gef.

2: $\mathbf{stplhs}$ – Real (Kind=nag_wp) Output

On exit: the current value of the left-hand side of the termination criterion used by f11gef.

3: $\mathbf{stprhs}$ – Real (Kind=nag_wp) Output

On exit: the current value of the right-hand side of the termination criterion used by f11gef.

4: $\mathbf{anorm}$ – Real (Kind=nag_wp) Output

On exit: for CG and SYMMLQ methods, the norm ${‖A‖}_1={‖A‖}_{\infty }$ when either it has been supplied to f11gdf or it has been estimated by f11gef (see also Sections 3 and 5 in f11gdf). Otherwise, $\mathbf{anorm}=0.0$ is returned.

For MINRES method, an estimate of the infinity norm of the preconditioned matrix operator.

5: $\mathbf{sigmax}$ – Real (Kind=nag_wp) Output

On exit: for CG and SYMMLQ methods, the current estimate of the largest singular value ${\sigma }_1\left(\overline{A}\right)$ of the preconditioned iteration matrix $\overline{A}=E^{-1}A{E}^{-\mathrm{T}}$, when either it has been supplied to f11gdf or it has been estimated by f11gef (see also Sections 3 and 5 in f11gdf). Note that if $\mathbf{its}<\mathbf{itn}$ then sigmax contains the final estimate. If, on final exit from f11gef, $\mathbf{its}=\mathbf{itn}$, the estimation of ${\sigma }_1\left(\overline{A}\right)$ may have not converged; in this case you should look at the value returned in sigerr. Otherwise, $\mathbf{sigmax}=0.0$ is returned.

For MINRES method, an estimate of the final transformed residual.

6: $\mathbf{its}$ – Integer Output

On exit: for CG and SYMMLQ methods, the number of iterations employed so far in the computation of the estimate of ${\sigma }_1\left(\overline{A}\right)$, the largest singular value of the preconditioned matrix $\overline{A}=E^{-1}A{E}^{-\mathrm{T}}$, when ${\sigma }_1\left(\overline{A}\right)$ has been estimated by f11gef using the bisection method (see also Sections 3, 5 and 9 in f11gdf). Otherwise, $\mathbf{its}=0$ is returned.

7: $\mathbf{sigerr}$ – Real (Kind=nag_wp) Output

On exit: for CG and SYMMLQ methods, if ${\sigma }_1\left(\overline{A}\right)$ has been estimated by f11gef using bisection,

$$\mathbf{sigerr}=\max \left(\frac{\left|{\sigma }_1^{\left(k\right)}-{\sigma }_1^{\left(k-1\right)}\right|}{{\sigma }_1^{\left(k\right)}},\frac{\left|{\sigma }_1^{\left(k\right)}-{\sigma }_1^{\left(k-2\right)}\right|}{{\sigma }_1^{\left(k\right)}}\right)\text{,}$$

where $k=\mathbf{its}$ denotes the iteration number. The estimation has converged if $\mathbf{sigerr}\le \mathbf{sigtol}$ where sigtol is an input argument to f11gdf. Otherwise, $\mathbf{sigerr}=0.0$ is returned.

For MINRES method, an estimate of the condition number of the preconditioned matrix.

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

On entry: the array work as returned by f11gef (see also Section 3 in f11gef).

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

On entry: the dimension of the array work as declared in the (sub)program from which f11gff is called (see also Section 5 in f11gdf).

Constraint: $\mathbf{lwork}\ge 120$.

Note:  although the minimum value of lwork ensures the correct functioning of f11gff, a larger value is required by the iterative solver f11gef (see also Section 5 in f11gdf).

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

On entry: ifail must be set to $0$, $-1\text{ or }1$. If you are unfamiliar with this argument you should refer to Section 4 in the Introduction to the NAG Library FL Interface for details.

For environments where it might be inappropriate to halt program execution when an error is detected, the value $-1\text{ or }1$ is recommended. If the output of error messages is undesirable, then the value $1$ is recommended. Otherwise, if you are not familiar with this argument, the recommended value is $0$. When the value $-\mathbf{1}\text{ or }\mathbf{1}$ is used it is essential to test the value of ifail on exit.

On 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

$\mathbf{ifail}=1$

f11gff has been called out of sequence.

$\mathbf{ifail}=-9$

On entry, $\mathbf{lwork}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{lwork}\ge 120$.

$\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

8 Parallelism and Performance

9 Further Comments

10 Example