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

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_sparse_complex_herm_basic_diag (f11gt)

## Purpose

nag_sparse_complex_herm_basic_diag (f11gt) is the third in a suite of three functions for the iterative solution of a complex Hermitian system of simultaneous linear equations (see Golub and Van Loan (1996)). nag_sparse_complex_herm_basic_diag (f11gt) returns information about the computations during an iteration and/or after this has been completed. The first function of the suite, nag_sparse_complex_herm_basic_setup (f11gr), is a setup function, the second function, nag_sparse_complex_herm_basic_solver (f11gs) is the proper iterative solver.
These three functions are suitable for the solution of large sparse complex Hermitian systems of equations.

## Syntax

[itn, stplhs, stprhs, anorm, sigmax, its, sigerr, ifail] = f11gt(work)
[itn, stplhs, stprhs, anorm, sigmax, its, sigerr, ifail] = nag_sparse_complex_herm_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_complex_herm_basic_diag (f11gt) returns information about the solution process. It can be called both during a monitoring step of the solver nag_sparse_complex_herm_basic_solver (f11gs) or after this solver has completed its tasks. Calling nag_sparse_complex_herm_basic_diag (f11gt) at any other time will result in an error condition being raised.
For further information you should read the documentation for nag_sparse_complex_herm_basic_setup (f11gr) and nag_sparse_complex_herm_basic_solver (f11gs).

## 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)$ – complex array
lwork, the dimension of the array, must satisfy the constraint $\mathit{lwork}\ge 120$.
The array work as returned by nag_sparse_complex_herm_basic_solver (f11gs) (see also Description in nag_sparse_complex_herm_basic_solver (f11gs)).

None.

### Output Parameters

1:     $\mathrm{itn}$int64int32nag_int scalar
The number of iterations carried out by nag_sparse_complex_herm_basic_solver (f11gs).
2:     $\mathrm{stplhs}$ – double scalar
The current value of the left-hand side of the termination criterion used by nag_sparse_complex_herm_basic_solver (f11gs).
3:     $\mathrm{stprhs}$ – double scalar
The current value of the right-hand side of the termination criterion used by nag_sparse_complex_herm_basic_solver (f11gs).
4:     $\mathrm{anorm}$ – double scalar
The norm ${‖A‖}_{1}={‖A‖}_{\infty }$ when either it has been supplied to nag_sparse_complex_herm_basic_setup (f11gr) or it has been estimated by nag_sparse_complex_herm_basic_solver (f11gs) (see also Description and Arguments in nag_sparse_complex_herm_basic_setup (f11gr)).
Otherwise, ${\mathbf{anorm}}=0.0$ is returned.
5:     $\mathrm{sigmax}$ – double scalar
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{H}}$, when either it has been supplied to nag_sparse_complex_herm_basic_setup (f11gr) or it has been estimated by nag_sparse_complex_herm_basic_solver (f11gs) (see also Description and Arguments in nag_sparse_complex_herm_basic_setup (f11gr)). Note that if ${\mathbf{its}}<{\mathbf{itn}}$ then sigmax contains the final estimate. If, on final exit from nag_sparse_complex_herm_basic_solver (f11gs), ${\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.
6:     $\mathrm{its}$int64int32nag_int scalar
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{H}}$, when ${\sigma }_{1}\left(\stackrel{-}{A}\right)$ has been estimated by nag_sparse_complex_herm_basic_solver (f11gs) using the bisection method (see also Description, Arguments and Further Comments in nag_sparse_complex_herm_basic_setup (f11gr)). Otherwise, ${\mathbf{its}}=0$ is returned.
7:     $\mathrm{sigerr}$ – double scalar
If ${\sigma }_{1}\left(\stackrel{-}{A}\right)$ has been estimated by nag_sparse_complex_herm_basic_solver (f11gs) 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_complex_herm_basic_setup (f11gr).
Otherwise, ${\mathbf{sigerr}}=0.0$ is returned.
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_complex_herm_basic_diag (f11gt) has been called out of sequence. For example, the last call to nag_sparse_complex_herm_basic_solver (f11gs) did not return ${\mathbf{irevcm}}=3$ or $4$.
${\mathbf{ifail}}=-99$
An unexpected error has been triggered by this routine. Please contact NAG.
${\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_complex_herm_basic_setup (f11gr).
```function f11gt_example

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

% Solve sparse Hermitian system Ax = b using CG method with
% Incomplete Cholesky preconditioning (IC)

% Define A and b
n  = int64(9);
nz = int64(23);
a    = complex(zeros(3*nz,1));
irow = zeros(3*nz, 1, 'int64');
icol = zeros(3*nz, 1, 'int64');
a(1:nz) = [ 6 + 0i;         -1 + 1i; 6 + 0i;         0 + 1i; 5 + 0i;
5 + 0i;          2 - 2i; 4 + 0i;         1 + 1i; 2 + 0i; 6 + 0i;
-4 + 3i; 0 + 1i; -1 + 0i; 6 + 0i;        -1 - 1i; 0 - 1i; 9 + 0i;
1 + 3i; 1 + 2i; -1 + 0i; 1 + 4i; 9 + 0i];

irow(1:nz) = [1; 2;2; 3;3;  4; 5;5; 6;6;6;  7;7;7;7; 8;8;8;  9;9;9;9;9];
icol(1:nz) = [1; 1;2; 2;3;  4; 1;5; 3;4;6;  2;5;6;7; 4;6;8;  1;5;6;8;9];

b = [ 8 + 54i; -10 - 92i; 25 + 27i;
26 - 28i;  54 + 12i; 26 - 22i;
47 + 65i;  71 - 57i; 60 + 70i];

% Setup IC factorization
lfill  = int64(0);
dtol   = 0;
mic    = 'N';
dscale = 0;
ipiv   = zeros(n, 1, 'int64');

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

% Iterative method setup
method = 'CG    ';
precon = 'Preconditioned';
tol    = (x02aj)^(3/8);
maxitn = int64(20);
anorm  = 0;
sigmax = 0;
maxits = int64(9);
monit  = int64(2);

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

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

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

if (irevcm == 1)
% v = Au
[v, ifail] = f11xs( ...
a(1:nz), irow(1:nz), icol(1:nz), 'N', u);
elseif (irevcm == 2)
% Solve (IC)v = u
[v, ifail] = f11jp( ...
a, irow, icol, ipiv, istr, 'N', u);
elseif (irevcm == 3)
% Monitoring
[itn, stplhs, stprhs, anorm, sigmax, its, sigerr, ifail] = ...
f11gt(work);
fprintf('\nMonitoring at iteration number %2d\n',itn);
fprintf('residual norm:              %14.4e\n', stplhs);
fprintf('\n   Solution Vector\n');
disp(u);
fprintf('\n   Residual Vector\n');
disp(v);
end
end

% Get information about the computation
[itn, stplhs, stprhs, anorm, sigmax, its, sigerr, ifail] = ...
f11gt(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\n');
disp(u);
fprintf('\n   Residual Vector\n');
disp(v);

```
```f11gt example results

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

Solution Vector
0.2142 + 4.5333i
-1.6589 -12.6722i
2.4101 + 7.4551i
4.4400 - 6.4174i
9.1135 + 3.7812i
4.4419 - 4.0382i
1.4757 + 1.2662i
8.4872 - 3.5347i
5.9948 + 0.9685i

Residual Vector
-1.8370 + 3.6956i
-0.6501 + 0.2546i
-0.1262 - 0.1362i
-0.1312 + 0.1413i
-1.1471 + 0.7339i
-0.5505 - 1.0535i
1.7165 - 1.4614i
-0.3583 + 0.2876i
-0.3028 - 0.3532i

Monitoring at iteration number  4
residual norm:                  1.4602e+00

Solution Vector
1.0061 + 8.9847i
1.9637 - 7.9768i
3.0067 + 7.0285i
3.9830 - 5.9636i
5.0390 + 5.0432i
6.0488 - 4.0771i
6.9710 + 3.0168i
8.0118 - 1.9806i
9.0074 + 0.9646i

Residual Vector
0.0115 - 0.0282i
0.0135 - 0.1734i
0.0182 + 0.0196i
0.0189 - 0.0204i
-0.0909 - 0.1090i
-0.2389 + 0.3244i
0.1903 - 0.0155i
0.0516 - 0.0414i
0.0436 + 0.0509i

Number of iterations for convergence:        5
Residual norm:                               9.0594e-14
Right-hand side of termination criteria:     2.8433e-03
i-norm of matrix a:                          2.2000e+01

Solution Vector
1.0000 + 9.0000i
2.0000 - 8.0000i
3.0000 + 7.0000i
4.0000 - 6.0000i
5.0000 + 5.0000i
6.0000 - 4.0000i
7.0000 + 3.0000i
8.0000 - 2.0000i
9.0000 + 1.0000i

Residual Vector
1.0e-13 *

-0.0178 + 0.0000i
0.0355 - 0.2842i
-0.0355 + 0.0355i
0.0355 - 0.0711i
-0.0711 + 0.0355i
-0.0711 + 0.0000i
0.0000 + 0.0000i
0.0000 - 0.0711i
0.0000 - 0.1421i

```

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2015