Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_sparse_real_symm_basic_diag (f11gf)

## Purpose

nag_sparse_real_symm_basic_diag (f11gf) is the third in a suite of three functions for the iterative solution of a symmetric system of simultaneous linear equations (see Golub and Van Loan (1996)). nag_sparse_real_symm_basic_diag (f11gf) returns information about the computations during an iteration and/or after this has been completed. The first function of the suite, nag_sparse_real_symm_basic_setup (f11gd), is a setup function, the second function, nag_sparse_real_symm_basic_solver (f11ge) is the proper iterative solver.
These three functions are suitable for the solution of large sparse symmetric systems of equations.

## Syntax

[itn, stplhs, stprhs, anorm, sigmax, its, sigerr, ifail] = f11gf(work)
[itn, stplhs, stprhs, anorm, sigmax, its, sigerr, ifail] = nag_sparse_real_symm_basic_diag(work)
Note: the interface to this routine has changed since earlier releases of the toolbox:
 At Mark 22: lwork was removed from the interface

## Description

nag_sparse_real_symm_basic_diag (f11gf) returns information about the solution process. It can be called both during a monitoring step of the solver nag_sparse_real_symm_basic_solver (f11ge), or after this solver has completed its tasks. Calling nag_sparse_real_symm_basic_diag (f11gf) at any other time will result in an error condition being raised.
For further information you should read the documentation for nag_sparse_real_symm_basic_setup (f11gd) and nag_sparse_real_symm_basic_solver (f11ge).

## References

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{work}\left(\mathit{lwork}\right)$ – double array
lwork, the dimension of the array, must satisfy the constraint $\mathit{lwork}\ge 120$.
The array work as returned by nag_sparse_real_symm_basic_solver (f11ge) (see also Description in nag_sparse_real_symm_basic_solver (f11ge)).

None.

### Output Parameters

1:     $\mathrm{itn}$int64int32nag_int scalar
The number of iterations carried out by nag_sparse_real_symm_basic_solver (f11ge).
2:     $\mathrm{stplhs}$ – double scalar
The current value of the left-hand side of the termination criterion used by nag_sparse_real_symm_basic_solver (f11ge).
3:     $\mathrm{stprhs}$ – double scalar
The current value of the right-hand side of the termination criterion used by nag_sparse_real_symm_basic_solver (f11ge).
4:     $\mathrm{anorm}$ – double scalar
For CG and SYMMLQ methods, the norm ${‖A‖}_{1}={‖A‖}_{\infty }$ when either it has been supplied to nag_sparse_real_symm_basic_setup (f11gd) or it has been estimated by nag_sparse_real_symm_basic_solver (f11ge) (see also Description and Arguments in nag_sparse_real_symm_basic_setup (f11gd)). Otherwise, ${\mathbf{anorm}}=0.0$ is returned.
For MINRES method, an estimate of the infinity norm of the preconditioned matrix operator.
5:     $\mathrm{sigmax}$ – double scalar
For CG and SYMMLQ methods, the current estimate of the largest singular value ${\sigma }_{1}\left(\stackrel{-}{A}\right)$ of the preconditioned iteration matrix $\stackrel{-}{A}={E}^{-1}A{E}^{-\mathrm{T}}$, when either it has been supplied to nag_sparse_real_symm_basic_setup (f11gd) or it has been estimated by nag_sparse_real_symm_basic_solver (f11ge) (see also Description and Arguments in nag_sparse_real_symm_basic_setup (f11gd)). Note that if ${\mathbf{its}}<{\mathbf{itn}}$ then sigmax contains the final estimate. If, on final exit from nag_sparse_real_symm_basic_solver (f11ge), ${\mathbf{its}}={\mathbf{itn}}$, then the estimation of ${\sigma }_{1}\left(\stackrel{-}{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:     $\mathrm{its}$int64int32nag_int scalar
For CG and SYMMLQ methods, the number of iterations employed so far in the computation of the estimate of ${\sigma }_{1}\left(\stackrel{-}{A}\right)$, the largest singular value of the preconditioned matrix $\stackrel{-}{A}={E}^{-1}A{E}^{-\mathrm{T}}$, when ${\sigma }_{1}\left(\stackrel{-}{A}\right)$ has been estimated by nag_sparse_real_symm_basic_solver (f11ge) using the bisection method (see also Description, Arguments and Further Comments in nag_sparse_real_symm_basic_setup (f11gd)). Otherwise, ${\mathbf{its}}=0$ is returned.
7:     $\mathrm{sigerr}$ – double scalar
For CG and SYMMLQ methods, if ${\sigma }_{1}\left(\stackrel{-}{A}\right)$ has been estimated by nag_sparse_real_symm_basic_solver (f11ge) using bisection,
 $sigerr=maxσ1k-σ1k-1σ1k,σ1k-σ1k-2σ1k ,$
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 nag_sparse_real_symm_basic_setup (f11gd). Otherwise, ${\mathbf{sigerr}}=0.0$ is returned.
For MINRES method, an estimate of the condition number of the preconditioned matrix.
8:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{ifail}}={\mathbf{0}}$ unless the function detects an error (see Error Indicators and Warnings).

## Error Indicators and Warnings

Errors or warnings detected by the function:
${\mathbf{ifail}}=-i$
If ${\mathbf{ifail}}=-i$, parameter $i$ had an illegal value on entry. The parameters are numbered as follows:
1: itn, 2: stplhs, 3: stprhs, 4: anorm, 5: sigmax, 6: its, 7: sigerr, 8: work, 9: lwork, 10: ifail.
It is possible that ifail refers to a parameter that is omitted from the MATLAB interface. This usually indicates that an error in one of the other input parameters has caused an incorrect value to be inferred.
${\mathbf{ifail}}=1$
nag_sparse_real_symm_basic_diag (f11gf) has been called out of sequence. For example, the last call to nag_sparse_real_symm_basic_solver (f11ge) did not return ${\mathbf{irevcm}}=3$ or $4$.
${\mathbf{ifail}}=-99$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

Not applicable.

None.

## Example

See Example in nag_sparse_real_symm_basic_setup (f11gd).
```function f11gf_example

fprintf('f11gf example results\n\n');

% Sparse matrix A
n    = int64(7);
nz   = int64(16);
a    = zeros(1000,1);
irow = zeros(1000,1,'int64');
icol = irow;

a(1:16)    = [4  1  5  2  2  3 -1  1  4  1 -2  3  2 -1 -2  5];
irow(1:16) = [1  2  2  3  4  4  5  5  5  6  6  6  7  7  7  7];
icol(1:16) = [1  1  2  3  2  4  1  4  5  2  5  6  1  2  3  7];

% Incomplete Cholesky factorization, zero fill
lfill  = int64(0);
dtol   = 0;
mic    = 'N';
dscale = 0;
ipiv   = zeros(n, 1, 'int64');

[a, irow, icol, ipiv, istr, nnzc, npivm, ifail] = ...
f11ja( ...
nz, a, irow, icol, lfill, dtol, mic, dscale, ipiv);

% Solver setup
method = 'CG';
precon = 'P';
tol    = 1e-6;
maxitn = int64(20);
anorm  = 0;
sigmax = 0;
maxits = int64(7);
monit  = int64(2);

[lwreq, work, ifail] = ...
f11gd(method, precon, n, tol, maxitn, anorm, sigmax, ...
maxits, monit, 'sigcmp', 'S', 'norm_p', '1');

% Solver inputs
irevcm = int64(0);
u      = zeros(n,1);
v      = [15; 18; -8; 21; 11; 10; 29];
wgt    = zeros(n,1);

% Reverse communication loop
while (irevcm ~= 4)
[irevcm, u, v, work, ifail] = f11ge( ...
irevcm, u, v, wgt, work);
if (irevcm == 1)
% v = Au
[v, ifail] = f11xe( ...
a, irow, icol, 'N', u, 'nz', nz);
elseif (irevcm == 2)
% preconditioner
[v, ifail] = f11jb( ...
a, irow, icol, ipiv, istr, 'N', u);
elseif (irevcm == 3)
[itn, stplhs, stprhs, anorm, sigmax, its, sigerr, ifail] = ...
f11gf(work);

fprintf('\nMonitoring at iteration number %d\n',itn);
fprintf('residual norm: %14.4e\n\n', stplhs);
fprintf('   Solution Vector  Residual Vector\n');
fprintf('%16.4f  %16.4e\n', [u'; v']);
end
end

% Get information about the computation
[itn, stplhs, stprhs, anorm, sigmax, its, sigerr, ifail] = f11gf(work);
fprintf('\nNumber of iterations for convergence: %d\n', itn);
fprintf('Residual norm:                           %14.4e\n', stplhs);
fprintf('Right-hand side of termination criteria: %14.4e\n', stprhs);
fprintf('i-norm of matrix a:                      %14.4e\n', anorm);
fprintf('\n   Solution Vector  Residual Vector\n');
fprintf('%16.4f  %12.2e\n', [u'; v']);

```
```f11gf example results

Monitoring at iteration number 2
residual norm:     1.9938e+00

Solution Vector  Residual Vector
0.9632       -2.2960e-01
1.9934        2.2254e-01
3.0583        9.5827e-02
4.1453       -2.5155e-01
4.8289       -1.7160e-01
5.6630        6.7533e-01
7.1062       -3.4737e-01

Monitoring at iteration number 4
residual norm:     6.6574e-03

Solution Vector  Residual Vector
0.9994       -1.0551e-03
2.0011       -2.4675e-03
3.0008       -1.7116e-05
3.9996        4.4929e-05
4.9991        2.1359e-03
5.9993       -8.7482e-04
7.0007        6.2045e-05

Number of iterations for convergence: 5
Residual norm:                               2.0428e-14
Right-hand side of termination criteria:     3.9200e-04
i-norm of matrix a:                          1.0000e+01

Solution Vector  Residual Vector
1.0000      0.00e+00
2.0000      0.00e+00
3.0000     -2.66e-15
4.0000     -3.55e-15
5.0000     -5.33e-15
6.0000      1.78e-15
7.0000      7.11e-15
```