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_complex_gen_basic_diag (f11bt)

## Purpose

nag_sparse_complex_gen_basic_diag (f11bt) is the third in a suite of three functions for the iterative solution of a complex general (non-Hermitian) system of simultaneous linear equations (see Golub and Van Loan (1996)). nag_sparse_complex_gen_basic_diag (f11bt) returns information about the computations during an iteration and/or after this has been completed. The first function of the suite, nag_sparse_complex_gen_basic_setup (f11br), is a setup function; the second function, nag_sparse_complex_gen_basic_solver (f11bs), is the iterative solver itself.
These three functions are suitable for the solution of large sparse general (non-Hermitian) systems of equations.

## Syntax

[itn, stplhs, stprhs, anorm, sigmax, work, ifail] = f11bt(work, 'lwork', lwork)
[itn, stplhs, stprhs, anorm, sigmax, work, ifail] = nag_sparse_complex_gen_basic_diag(work, 'lwork', lwork)

## Description

nag_sparse_complex_gen_basic_diag (f11bt) returns information about the solution process. It can be called either during a monitoring step of nag_sparse_complex_gen_basic_solver (f11bs) or after nag_sparse_complex_gen_basic_solver (f11bs) has completed its tasks. Calling nag_sparse_complex_gen_basic_diag (f11bt) at any other time will result in an error condition being raised.
For further information you should read the documentation for nag_sparse_complex_gen_basic_setup (f11br) and nag_sparse_complex_gen_basic_solver (f11bs).

## 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) – complex array
lwork, the dimension of the array, must satisfy the constraint lwork120${\mathbf{lwork}}\ge 120$.
The array work as returned by nag_sparse_complex_gen_basic_solver (f11bs) (see also Sections [Description] and [Parameters] in (f11bs)).

### 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_complex_gen_basic_diag (f11bt) is called (see also nag_sparse_complex_gen_basic_setup (f11br)).
Constraint: lwork120${\mathbf{lwork}}\ge 120$.
Note:  although the minimum value of lwork ensures the correct functioning of nag_sparse_complex_gen_basic_diag (f11bt), a larger value is required by the iterative solver nag_sparse_complex_gen_basic_solver (f11bs) (see also nag_sparse_complex_gen_basic_setup (f11br)).

None.

### Output Parameters

1:     itn – int64int32nag_int scalar
The number of iterations carried out by nag_sparse_complex_gen_basic_solver (f11bs).
2:     stplhs – double scalar
The current value of the left-hand side of the termination criterion used by nag_sparse_complex_gen_basic_solver (f11bs).
3:     stprhs – double scalar
The current value of the right-hand side of the termination criterion used by nag_sparse_complex_gen_basic_solver (f11bs).
4:     anorm – double scalar
If iterm = 1${\mathbf{iterm}}=1$ in the previous call to nag_sparse_complex_gen_basic_setup (f11br), 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_complex_gen_basic_solver (f11bs); 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_complex_gen_basic_setup (f11br), the current estimate of the largest singular value σ1(A)${\sigma }_{1}\left(\stackrel{-}{A}\right)$ of the preconditioned iteration matrix when it is used by the termination criterion in nag_sparse_complex_gen_basic_solver (f11bs), either when it has been supplied to nag_sparse_complex_gen_basic_setup (f11br) or it has been estimated by nag_sparse_complex_gen_basic_solver (f11bs) (see also Sections [Description] and [Parameters] in (f11br)); otherwise, sigmax = 0.0${\mathbf{sigmax}}=0.0$ is returned.
6:     work(lwork) – complex array
Communication array, used to store information between calls to nag_sparse_complex_gen_basic_diag (f11bt).
7:     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_complex_gen_basic_diag (f11bt) has been called out of sequence. For example, the last call to nag_sparse_complex_gen_basic_solver (f11bs) did not return irevcm = 3${\mathbf{irevcm}}=3$ or 4$4$.

Not applicable.

None.

## Example

```function nag_sparse_complex_gen_basic_diag_example
method = 'TFQMR   ';
precon = 'P';
n = 8;
m = int64(1);
tol = 1e-08;
maxitn = int64(20);
anorm = 0;
sigmax = 0;
monit = int64(2);
lwork = int64(6000);
nz=24;
a=complex(zeros(10000,1));
a(1:24)=[ 2 + 1.i,
-1 + 1.i,
1 - 3.i,
4 + 7.i,
-3 + 0.i,
2 + 4.i,
-7 - 5.i,
2 + 1.i,
3 + 2.i,
-4 + 2.i,
0 + 1.i,
5 - 3.i,
-1 + 2.i,
8 + 6.i,
-3 - 4.i,
-6 - 2.i,
5 - 2.i,
2 + 0.i,
0 - 5.i,
-1 + 5.i,
6 + 2.i,
-1 + 4.i,
2 + 0.i,
3 + 3.i];
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];
ipivp = zeros(n,1,'int64');
ipivq = zeros(n,1,'int64');
irevcm = int64(0);
lfill = int64(0);
dtol = 0;
milu = 'N';
wgt = zeros(8,1);
u = complex(zeros(8,1));
v = [ 7 + 11.i;
1 + 24.i;
-13 - 18.i;
-10 + 3.i;
23 + 14.i;
17 - 7.i;
15 - 3.i;
-3 + 20.i];
[a, irow, icol, ipivp, ipivq, istr, idiag, nnzc, npivm, ifail] = ...
nag_sparse_complex_gen_precon_ilu(int64(nz), a, irow, icol, lfill, ...
dtol, milu, ipivp, ipivq);

[lwreq, work, ifail] = ...
nag_sparse_complex_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_complex_gen_basic_solver(irevcm, u, v, wgt, work);

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

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

Solution Vector
+6.9055e-01 +      +1.4236e+00I
+7.3931e-02 +      -1.1880e+00I
+1.4778e+00 +      +4.7846e-01I
+5.6572e+00 +      -3.0786e+00I
+1.4243e+00 +      -1.1246e+00I
+1.0374e-01 +      +1.9740e+00I
+4.4985e-01 +      -1.2715e+00I
+2.5704e+00 +      +1.7578e+00I

Residual Vector
+1.7772e+00 +      +4.6797e+00I
+1.0774e+00 +      +6.4600e+00I
-3.2812e+00 +      -1.1314e+01I
-3.8698e+00 +      -1.6438e+00I
+8.9912e+00 +      +1.1100e+01I
+9.7428e+00 +      -4.6218e-01I
+3.1668e+00 +      +2.8721e+00I
-1.0323e+01 +      +1.5837e+00I

Number of iterations for convergence: 4
Residual norm:                               3.2053e-11
Right-hand side of termination criteria:     8.9100e-06
i-norm of matrix a:                          2.7000e+01

Solution Vector
+1.0000e+00 +      +1.0000e+00I
+2.0000e+00 +      -1.0000e+00I
+3.0000e+00 +      +1.0000e+00I
+4.0000e+00 +      -1.0000e+00I
+3.0000e+00 +      -1.0000e+00I
+2.0000e+00 +      +1.0000e+00I
+1.0000e+00 +      -1.0000e+00I
-2.2003e-12 +      +3.0000e+00I

Residual Vector
-2.3430e-12 +      -8.6331e-13I
-3.3342e-12 +      -5.2509e-12I
+2.7374e-12 +      +1.3145e-13I
+3.9613e-13 +      -2.2400e-12I
-3.1548e-12 +      +1.0996e-12I
-6.5015e-13 +      +2.1778e-12I
+8.1712e-13 +      +1.0996e-12I
+4.6381e-12 +      +1.1191e-12I

```
```function f11bt_example
method = 'TFQMR   ';
precon = 'P';
n = 8;
m = int64(1);
tol = 1e-08;
maxitn = int64(20);
anorm = 0;
sigmax = 0;
monit = int64(2);
lwork = int64(6000);
nz=24;
a=complex(zeros(10000,1));
a(1:24)=[ 2 + 1.i,
-1 + 1.i,
1 - 3.i,
4 + 7.i,
-3 + 0.i,
2 + 4.i,
-7 - 5.i,
2 + 1.i,
3 + 2.i,
-4 + 2.i,
0 + 1.i,
5 - 3.i,
-1 + 2.i,
8 + 6.i,
-3 - 4.i,
-6 - 2.i,
5 - 2.i,
2 + 0.i,
0 - 5.i,
-1 + 5.i,
6 + 2.i,
-1 + 4.i,
2 + 0.i,
3 + 3.i];
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];
ipivp = zeros(n,1,'int64');
ipivq = zeros(n,1,'int64');
irevcm = int64(0);
lfill = int64(0);
dtol = 0;
milu = 'N';
wgt = zeros(8,1);
u = complex(zeros(8,1));
v = [ 7 + 11.i;
1 + 24.i;
-13 - 18.i;
-10 + 3.i;
23 + 14.i;
17 - 7.i;
15 - 3.i;
-3 + 20.i];
[a, irow, icol, ipivp, ipivq, istr, idiag, nnzc, npivm, ifail] = ...
f11dn(int64(nz), a, irow, icol, lfill, dtol, milu, ipivp, ipivq);

[lwreq, work, ifail] = ...
f11br(method, precon, int64(n), m, tol, maxitn, anorm, sigmax, monit, lwork, 'norm_p', '1');

while (irevcm ~= 4)
[irevcm, u, v, work, ifail] = f11bs(irevcm, u, v, wgt, work);

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

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

Solution Vector
+6.9055e-01 +      +1.4236e+00I
+7.3931e-02 +      -1.1880e+00I
+1.4778e+00 +      +4.7846e-01I
+5.6572e+00 +      -3.0786e+00I
+1.4243e+00 +      -1.1246e+00I
+1.0374e-01 +      +1.9740e+00I
+4.4985e-01 +      -1.2715e+00I
+2.5704e+00 +      +1.7578e+00I

Residual Vector
+1.7772e+00 +      +4.6797e+00I
+1.0774e+00 +      +6.4600e+00I
-3.2812e+00 +      -1.1314e+01I
-3.8698e+00 +      -1.6438e+00I
+8.9912e+00 +      +1.1100e+01I
+9.7428e+00 +      -4.6218e-01I
+3.1668e+00 +      +2.8721e+00I
-1.0323e+01 +      +1.5837e+00I

Number of iterations for convergence: 4
Residual norm:                               3.0698e-11
Right-hand side of termination criteria:     8.9100e-06
i-norm of matrix a:                          2.7000e+01

Solution Vector
+1.0000e+00 +      +1.0000e+00I
+2.0000e+00 +      -1.0000e+00I
+3.0000e+00 +      +1.0000e+00I
+4.0000e+00 +      -1.0000e+00I
+3.0000e+00 +      -1.0000e+00I
+2.0000e+00 +      +1.0000e+00I
+1.0000e+00 +      -1.0000e+00I
-1.6542e-12 +      +3.0000e+00I

Residual Vector
-1.4246e-12 +      -1.8616e-12I
+6.1284e-13 +      -5.9011e-12I
+2.4336e-12 +      +1.1120e-12I
+1.6378e-12 +      -1.7870e-12I
-3.2188e-12 +      -8.7041e-14I
-1.3500e-12 +      +1.7879e-12I
-2.4869e-14 +      +1.1848e-12I
+3.7517e-12 +      +2.5224e-12I

```