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_gen_basic_diag (f11bf)

## Purpose

nag_sparse_real_gen_basic_diag (f11bf) is the third in a suite of three functions for the iterative solution of a real general (nonsymmetric) system of simultaneous linear equations (see Golub and Van Loan (1996)). nag_sparse_real_gen_basic_diag (f11bf) returns information about the computations during an iteration and/or after this has been completed. The first function of the suite, nag_sparse_real_gen_basic_setup (f11bd), is a setup function; the second function, nag_sparse_real_gen_basic_solver (f11be), is the iterative solver itself.
These three functions are suitable for the solution of large sparse general (nonsymmetric) systems of equations.

## Syntax

[itn, stplhs, stprhs, anorm, sigmax, ifail] = f11bf(work, 'lwork', lwork)
[itn, stplhs, stprhs, anorm, sigmax, ifail] = nag_sparse_real_gen_basic_diag(work, 'lwork', lwork)

## Description

nag_sparse_real_gen_basic_diag (f11bf) returns information about the solution process. It can be called either during a monitoring step of nag_sparse_real_gen_basic_solver (f11be) or after nag_sparse_real_gen_basic_solver (f11be) has completed its tasks. Calling nag_sparse_real_gen_basic_diag (f11bf) at any other time will result in an error condition being raised.
For further information you should read the documentation for nag_sparse_real_gen_basic_setup (f11bd) and nag_sparse_real_gen_basic_solver (f11be).

## 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({\mathbf{lwork}}\right)$ – double array
The array work as returned by nag_sparse_real_gen_basic_solver (f11be) (see also Description and Arguments in nag_sparse_real_gen_basic_solver (f11be)).

### Optional Input Parameters

1:     $\mathrm{lwork}$int64int32nag_int scalar
Default: the dimension of the array work.
The dimension of the array work (see also Arguments in nag_sparse_real_gen_basic_setup (f11bd)).
Constraint: ${\mathbf{lwork}}\ge 100$.
Note: although the minimum value of lwork ensures the correct functioning of nag_sparse_real_gen_basic_diag (f11bf), a larger value is required by the iterative solver nag_sparse_real_gen_basic_solver (f11be) (see also Arguments in nag_sparse_real_gen_basic_setup (f11bd)).

### Output Parameters

1:     $\mathrm{itn}$int64int32nag_int scalar
The number of iterations carried out by nag_sparse_real_gen_basic_solver (f11be).
2:     $\mathrm{stplhs}$ – double scalar
The current value of the left-hand side of the termination criterion used by nag_sparse_real_gen_basic_solver (f11be).
3:     $\mathrm{stprhs}$ – double scalar
The current value of the right-hand side of the termination criterion used by nag_sparse_real_gen_basic_solver (f11be).
4:     $\mathrm{anorm}$ – double scalar
If ${\mathbf{iterm}}=1$ in the previous call to nag_sparse_real_gen_basic_setup (f11bd), then anorm contains ${‖A‖}_{p}$, where $p=1$, $2$ or $\infty$, either supplied or, in the case of $1$ or $\infty$, estimated by nag_sparse_real_gen_basic_solver (f11be); otherwise ${\mathbf{anorm}}=0.0$.
5:     $\mathrm{sigmax}$ – double scalar
If ${\mathbf{iterm}}=2$ in the previous call to nag_sparse_real_gen_basic_setup (f11bd), the current estimate of the largest singular value ${\sigma }_{1}\left(\stackrel{-}{A}\right)$ of the preconditioned iteration matrix, either when it has been supplied to nag_sparse_real_gen_basic_setup (f11bd) or it has been estimated by nag_sparse_real_gen_basic_solver (f11be) (see also Description and Arguments in nag_sparse_real_gen_basic_setup (f11bd)); otherwise, ${\mathbf{sigmax}}=0.0$ is returned.
6:     $\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: work, 7: lwork, 8: ifail.
${\mathbf{ifail}}=1$
nag_sparse_real_gen_basic_diag (f11bf) has been called out of sequence. For example, the last call to nag_sparse_real_gen_basic_solver (f11be) 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_gen_basic_setup (f11bd).
```function f11bf_example

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

% Solve sparse system Ax = b iteratively using ILU preconditioner

% Define sparse matrix A and RHS B
n    = int64(8);
nz   = int64(24);
a    = zeros(3*nz, 1);
irow = zeros(3*nz, 1, 'int64');
icol = irow;
irow(1:nz) = int64(...
[1; 1; 1; 2; 2; 2; 3; 3; 4; 4; 4; 4;
5; 5; 5; 6; 6; 6; 7; 7; 7; 8; 8; 8]);
icol(1:nz) = int64(...
[1; 4; 8; 1; 2; 5; 3; 6; 1; 3; 4; 7;
2; 5; 7; 1; 3; 6; 3; 5; 7; 2; 6; 8]);
a(1:nz)    = [2;-1; 1; 4;-3; 2;-7; 2; 3;-4; 5; 5;
-1; 8;-3;-6; 5; 2;-5;-1; 6;-1; 2; 3];
b          = [6; 8;-9;46;17;21;22;34];

% ILU preconditioner
%     Input parameters
lfill = int64(0);
dtol  = 0;
milu  = 'No modification';
ipivp = zeros(n, 1, 'int64');
ipivq = zeros(n, 1, 'int64');
% Compute preconditioner
[a, irow, icol, ipivp, ipivq, istr, idiag, nnzc, npivm, ifail] = ...
f11da(...
nz, a, irow, icol, lfill, dtol, milu, ipivp, ipivq);

% Iterative Solution Setup
%      Input parameters
method = 'BICGSTAB';
precon = 'Preconditioned';
lpoly  = int64(1);
tol    = sqrt(x02aj);
maxitn = int64(20);
anorm  = 0;
sigmax = 0;
monit  = int64(1);
lwork  = int64(6000);
% Setup iterative method
[lwreq, work, ifail] = ...
f11bd(...
method, precon, n, lpoly, tol, maxitn, anorm, sigmax, ...
monit, lwork, 'norm_p', '1');

% Reverse communication loop calling iterative solver
irevcm = int64(0);
u      = zeros(n, 1);
v      = b;
wgt    = zeros(n, 1);

while (irevcm ~= 4)

[irevcm, u, v, work, ifail] = f11be(...
irevcm, u, v, wgt, work);

if (irevcm == -1)
% v = A^Tu
[v, ifail] = f11xa(...
'T', a(1:nz), irow(1:nz), icol(1:nz), 'N', u);
elseif (irevcm == 1)
% v = Au
[v, ifail] = f11xa(...
'N', a(1:nz), irow(1:nz), icol(1:nz), 'N', u);
elseif (irevcm == 2)
% Solve ILU v = u
[v, ifail] = f11db(...
'N', a, irow, icol, ipivp, ipivq, istr, idiag, 'N', u);
if (ifail ~= 0)
irevcm = 6;
end
elseif (irevcm == 3)
% Monitoring stage
[itn, stplhs, stprhs, anorm, sigmax, ifail] = ...
f11bf(work);
fprintf('\nMonitoring at iteration number %2d\n',itn);
fprintf('residual norm:              %14.4e\n', stplhs);
fprintf('\n   Solution Vector  Residual Vector\n');
for i = 1:n
fprintf('%16.4f %16.2e\n', u(i), v(i));
end
end
end

% Get information about the computation
[itn, stplhs, stprhs, anorm, sigmax, ifail] = ...
f11bf(work);

fprintf('\nNumber of iterations for convergence:     %4d\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');
for i = 1:n
fprintf('%16.4f %16.2e\n', u(i), v(i));
end

```
```f11bf example results

Monitoring at iteration number  1
residual norm:                  1.4059e+02

Solution Vector  Residual Vector
-4.5858         1.53e+01
1.0154         2.66e+01
-2.2234        -8.75e+00
6.0097         1.86e+01
1.3827         8.28e+00
-7.9070         2.04e+01
0.4427         9.61e+00
5.9248         3.31e+01

Monitoring at iteration number  2
residual norm:                  3.2742e+01

Solution Vector  Residual Vector
4.1642        -2.96e+00
4.9370        -5.55e+00
4.8101         8.21e-01
5.4324        -1.68e+01
5.8531         5.60e-01
11.9250        -1.91e+00
8.4826         1.01e+00
6.0625        -3.10e+00

Number of iterations for convergence:        3
Residual norm:                               1.0373e-08
Right-hand side of termination criteria:     5.8900e-06
i-norm of matrix a:                          1.1000e+01

Solution Vector  Residual Vector
1.0000        -1.36e-09
2.0000        -2.61e-09
3.0000         2.25e-10
4.0000        -3.22e-09
5.0000         6.30e-10
6.0000        -5.24e-10
7.0000         9.58e-10
8.0000        -8.49e-10
```