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:     work(lwork) – double array
lwork, the dimension of the array, must satisfy the constraint lwork100${\mathbf{lwork}}\ge 100$.
The array work as returned by nag_sparse_real_gen_basic_solver (f11be) (see also Sections [Description] and [Parameters] in (f11be)).

### Optional Input Parameters

1:     lwork – int64int32nag_int scalar
Default: The dimension of the array work.
The dimension of the array work as declared in the (sub)program from which nag_sparse_real_gen_basic_diag (f11bf) is called (see also Section [Parameters] in (f11bd)).
Constraint: lwork100${\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 Section [Parameters] in (f11bd)).

None.

### Output Parameters

1:     itn – int64int32nag_int scalar
The number of iterations carried out by nag_sparse_real_gen_basic_solver (f11be).
2:     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:     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:     anorm – double scalar
If iterm = 1${\mathbf{iterm}}=1$ in the previous call to nag_sparse_real_gen_basic_setup (f11bd), then anorm contains Ap${‖A‖}_{p}$, where p = 1$p=1$, 2$2$ or $\infty$, either supplied or, in the case of 1$1$ or $\infty$, estimated by nag_sparse_real_gen_basic_solver (f11be); otherwise anorm = 0.0${\mathbf{anorm}}=0.0$.
5:     sigmax – double scalar
If iterm = 2${\mathbf{iterm}}=2$ in the previous call to nag_sparse_real_gen_basic_setup (f11bd), the current estimate of the largest singular value σ1(A)${\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 Sections [Description] and [Parameters] in (f11bd)); otherwise, sigmax = 0.0${\mathbf{sigmax}}=0.0$ is returned.
6:     ifail – int64int32nag_int scalar
${\mathrm{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:
ifail = i${\mathbf{ifail}}=-i$
If ifail = i${\mathbf{ifail}}=-i$, parameter i$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.
ifail = 1${\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 irevcm = 3${\mathbf{irevcm}}=3$ or 4$4$.

Not applicable.

None.

## Example

```function nag_sparse_real_gen_basic_diag_example
method = 'BICGSTAB';
precon = 'P';
n = 8;
m = int64(1);
nz = 24;
a = zeros(10000, 1);
a(1:24) = [2;-1;1;4;-3;2;-7;2;3;-4;5;5;-1;8;-3;-6;5;2;-5;-1;6;-1;2;3];
irow = zeros(10000, 1, 'int64');
irow(1:24) = [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 = zeros(10000, 1, 'int64');
icol(1:24) = [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];
lfill = int64(0);
ipivp = zeros(8, 1, 'int64');
ipivq = zeros(8, 1, 'int64');
dtol = 0;
milu = 'N';
tol = 1e-08;
maxitn = int64(20);
anorm = 0;
sigmax = 0;
monit = int64(1);
lwork = int64(6000);
irevcm = int64(0);
u = zeros(8, 1);
v = [6; 8; -9; 46; 17; 21; 22; 34];
wgt = zeros(8, 1);
[a, irow, icol, ipivp, ipivq, istr, idiag, nnzc, npivm, ifail] = ...
nag_sparse_real_gen_precon_ilu(int64(nz), a, irow, icol, lfill,  ...
dtol, milu, ipivp, ipivq);
[lwreq, work, ifail] = ...
nag_sparse_real_gen_basic_setup(method, precon, int64(n), m, tol,  ...
maxitn, anorm, sigmax, monit, lwork, 'norm_p', '1');
while (irevcm ~= 4)
[irevcm, u, v, work, ifail] = ...
nag_sparse_real_gen_basic_solver(irevcm, u, v, wgt, work);

if (irevcm == -1)
[v, ifail] = ...
nag_sparse_real_gen_matvec('T', a(1:nz), irow(1:nz), icol(1:nz), 'N', u);
elseif (irevcm == 1)
[v, ifail] = ...
nag_sparse_real_gen_matvec('N', a(1:nz), irow(1:nz), icol(1:nz), 'N', u);
elseif (irevcm == 2)
[v, ifail] = ...
nag_sparse_real_gen_precon_ilu_solve('N', a, irow, icol, ipivp, ipivq,  ...
istr, idiag, 'N', u);
if (ifail ~= 0)
irevcm = 6;
end
elseif (irevcm == 3)
[itn, stplhs, stprhs, anorm, sigmax, ifail] =  ...
nag_sparse_real_gen_basic_diag(work);
fprintf('\nMonitoring at iteration number %d\nresidual norm: %14.4e\n',  ...
itn, stplhs);
fprintf('\n   Solution Vector  Residual Vector\n');
for i = 1:n
fprintf('%+16.4e %+16.4e\n', u(i), v(i));
end
end
end
% Get information about the computation
[itn, stplhs, stprhs, anorm, sigmax, ifail] =  ...
nag_sparse_real_gen_basic_diag(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');
for i = 1:n
fprintf('%+16.4e %+16.4e\n', u(i), v(i));
end
```
```

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

Solution Vector  Residual Vector
-4.5858e+00      +1.5256e+01
+1.0154e+00      +2.6624e+01
-2.2234e+00      -8.7498e+00
+6.0097e+00      +1.8602e+01
+1.3827e+00      +8.2821e+00
-7.9070e+00      +2.0416e+01
+4.4270e-01      +9.6094e+00
+5.9248e+00      +3.3055e+01

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

Solution Vector  Residual Vector
+4.1642e+00      -2.9585e+00
+4.9370e+00      -5.5523e+00
+4.8101e+00      +8.2070e-01
+5.4324e+00      -1.6828e+01
+5.8531e+00      +5.5975e-01
+1.1925e+01      -1.9150e+00
+8.4826e+00      +1.0081e+00
+6.0625e+00      -3.1004e+00

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

Solution Vector  Residual Vector
+1.0000e+00      -1.3686e-09
+2.0000e+00      -2.6364e-09
+3.0000e+00      +2.2691e-10
+4.0000e+00      -3.2518e-09
+5.0000e+00      +6.3661e-10
+6.0000e+00      -5.2943e-10
+7.0000e+00      +9.6707e-10
+8.0000e+00      -8.5718e-10

```
```function f11bf_example
method = 'BICGSTAB';
precon = 'P';
n = 8;
m = int64(1);
nz = 24;
a = zeros(10000, 1);
a(1:24) = [2; -1; 1; 4; -3; 2; -7; 2; 3; -4; 5; 5; -1; 8; -3; -6; 5; 2; -5; -1; 6; -1; 2; 3];
irow = zeros(10000, 1, 'int64');
irow(1:24) = [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 = zeros(10000, 1, 'int64');
icol(1:24) = [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];
lfill = int64(0);
ipivp = zeros(8, 1, 'int64');
ipivq = zeros(8, 1, 'int64');
dtol = 0;
milu = 'N';
tol = 1e-08;
maxitn = int64(20);
anorm = 0;
sigmax = 0;
monit = int64(1);
lwork = int64(6000);
irevcm = int64(0);
u = zeros(8, 1);
v = [6; 8; -9; 46; 17; 21; 22; 34];
wgt = zeros(8, 1);
[a, irow, icol, ipivp, ipivq, istr, idiag, nnzc, npivm, ifail] = ...
f11da(int64(nz), a, irow, icol, lfill, dtol, milu, ipivp, ipivq);
[lwreq, work, ifail] = ...
f11bd(method, precon, int64(n), m, tol, maxitn, anorm, sigmax, monit, lwork, 'norm_p', '1');
while (irevcm ~= 4)
[irevcm, u, v, work, ifail] = f11be(irevcm, u, v, wgt, work);

if (irevcm == -1)
[v, ifail] = f11xa('T', a(1:nz), irow(1:nz), icol(1:nz), 'N', u);
elseif (irevcm == 1)
[v, ifail] = f11xa('N', a(1:nz), irow(1:nz), icol(1:nz), 'N', u);
elseif (irevcm == 2)
[v, ifail] = f11db('N', a, irow, icol, ipivp, ipivq, istr, idiag, 'N', u);
if (ifail ~= 0)
irevcm = 6;
end
elseif (irevcm == 3)
[itn, stplhs, stprhs, anorm, sigmax, ifail] = f11bf(work);
fprintf('\nMonitoring at iteration number %d\nresidual norm: %14.4e\n', itn, stplhs);
fprintf('\n   Solution Vector  Residual Vector\n');
for i = 1:n
fprintf('%+16.4e %+16.4e\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: %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');
for i = 1:n
fprintf('%+16.4e %+16.4e\n', u(i), v(i));
end
```
```

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

Solution Vector  Residual Vector
-4.5858e+00      +1.5256e+01
+1.0154e+00      +2.6624e+01
-2.2234e+00      -8.7498e+00
+6.0097e+00      +1.8602e+01
+1.3827e+00      +8.2821e+00
-7.9070e+00      +2.0416e+01
+4.4270e-01      +9.6094e+00
+5.9248e+00      +3.3055e+01

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

Solution Vector  Residual Vector
+4.1642e+00      -2.9585e+00
+4.9370e+00      -5.5523e+00
+4.8101e+00      +8.2070e-01
+5.4324e+00      -1.6828e+01
+5.8531e+00      +5.5975e-01
+1.1925e+01      -1.9150e+00
+8.4826e+00      +1.0081e+00
+6.0625e+00      -3.1004e+00

Number of iterations for convergence: 3
Residual norm:                               5.3402e-09
Right-hand side of termination criteria:     5.5900e-06
i-norm of matrix a:                          1.1000e+01

Solution Vector  Residual Vector
+1.0000e+00      -6.9779e-10
+2.0000e+00      -1.3442e-09
+3.0000e+00      +1.1569e-10
+4.0000e+00      -1.6579e-09
+5.0000e+00      +3.2458e-10
+6.0000e+00      -2.6994e-10
+7.0000e+00      +4.9305e-10
+8.0000e+00      -4.3705e-10

```