hide long namesshow long names
hide short namesshow short names
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:
Mark 22: lwork has been 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:     work(lwork) – complex array
lwork, the dimension of the array, must satisfy the constraint lwork120lwork120.
The array work as returned by nag_sparse_complex_herm_basic_solver (f11gs) (see also Section [Description] in (f11gs)).

Optional Input Parameters

None.

Input Parameters Omitted from the MATLAB Interface

lwork

Output Parameters

1:     itn – int64int32nag_int scalar
The number of iterations carried out by nag_sparse_complex_herm_basic_solver (f11gs).
2:     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:     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:     anorm – double scalar
The norm A1 = AA1=A 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 Sections [Description] and [Parameters] in (f11gr)). Otherwise, anorm = 0.0anorm=0.0 is returned.
5:     sigmax – double scalar
The current estimate of the largest singular value σ1(A)σ1(A-) of the preconditioned iteration matrix A = E1AEHA-=E-1AE-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 Sections [Description] and [Parameters] in (f11gr)). Note that if its < itnits<itn then sigmax contains the final estimate. If, on final exit from nag_sparse_complex_herm_basic_solver (f11gs), its = itnits=itn, then the estimation of σ1(A)σ1(A-) may have not converged: in this case you should look at the value returned in sigerr. Otherwise, sigmax = 0.0sigmax=0.0 is returned.
6:     its – int64int32nag_int scalar
The number of iterations employed so far in the computation of the estimate of σ1(A)σ1(A-), the largest singular value of the preconditioned matrix A = E1AEHA-=E-1AE-H, when σ1(A)σ1(A-) has been estimated by nag_sparse_complex_herm_basic_solver (f11gs) using the bisection method (see also Sections [Description], [Parameters] and [Further Comments] in (f11gr)). Otherwise, its = 0its=0 is returned.
7:     sigerr – double scalar
If σ1(A)σ1(A-) has been estimated by nag_sparse_complex_herm_basic_solver (f11gs) using bisection,
sigerr = max ((|σ1(k)σ1(k1)|)/(σ1(k)),(|σ1(k)σ1(k2)|)/(σ1(k))) ,
sigerr=max(|σ1(k)-σ1(k-1)|σ1(k),|σ1(k)-σ1(k-2)|σ1(k)) ,
where k = itsk=its denotes the iteration number. The estimation has converged if sigerrsigtolsigerrsigtol where sigtol is an input parameter to nag_sparse_complex_herm_basic_setup (f11gr). Otherwise, sigerr = 0.0sigerr=0.0 is returned.
8:     ifail – int64int32nag_int scalar
ifail = 0ifail=0 unless the function detects an error (see [Error Indicators and Warnings]).

Error Indicators and Warnings

Errors or warnings detected by the function:
  ifail = iifail=-i
If ifail = iifail=-i, parameter ii 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.
  ifail = 1ifail=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 irevcm = 3irevcm=3 or 44.

Accuracy

Not applicable.

Further Comments

None.

Example

function nag_sparse_complex_herm_basic_diag_example
nz = 23;
a = zeros(10000,1);
a(1:nz) = [ 6 + 0.i;
           -1 + 1.i;
            6 + 0.i;
            0 + 1.i;
            5 + 0.i;
            5 + 0.i;
            2 - 2.i;
            4 + 0.i;
            1 + 1.i;
            2 + 0.i;
            6 + 0.i;
           -4 + 3.i;
            0 + 1.i;
           -1 + 0.i;
            6 + 0.i;
           -1 - 1.i;
            0 - 1.i;
            9 + 0.i;
            1 + 3.i;
            1 + 2.i;
           -1 + 0.i;
            1 + 4.i;
            9 + 0.i];
irow = zeros(10000, 1, 'int64');
irow(1:nz) = [int64(1);2;2;3;3;4;5;5;6;6;6;7;7;7;7;8;8;8;9;9;9;9;9];
icol = zeros(10000, 1, 'int64');
icol(1:nz) = [int64(1);1;2;2;3;4;1;5;3;4;6;2;5;6;7;4;6;8;1;5;6;8;9];
lfill = int64(0);
dtol = 0;
mic = 'N';
dscale = 0;
ipiv = [int64(0);0;0;0;0;0;0;0;0];
method = 'CG    ';
precon = 'P';
n = 9;
tol = 1e-06;
maxitn = int64(20);
anorm = 0;
sigmax = 0;
maxits = int64(9);
monit = int64(2);

irevcm = int64(0);
u = [complex(0);
      0 + 0i;
      0 + 0i;
      0 + 0i;
      0 + 0i;
      0 + 0i;
      0 + 0i;
      0 + 0i;
      0 + 0i];
v = [ 8 + 54i;
      -10 - 92i;
      25 + 27i;
      26 - 28i;
      54 + 12i;
      26 - 22i;
      47 + 65i;
      71 - 57i;
      60 + 70i];
wgt = [0; 0; 0; 0; 0; 0; 0; 0; 0];


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

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

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

  if (irevcm == 1)
    [v, ifail] = ...
     nag_sparse_complex_herm_matvec(a(1:nz), irow(1:nz), icol(1:nz), 'N', u);
    if (ifail ~= 0)
      irecvm = 6;
    end
  elseif (irevcm == 2)
    [v, ifail] = ...
     nag_sparse_complex_herm_precon_ilu_solve(a, irow, icol, ipiv, istr, 'N', u);
    if (ifail ~= 0)
      irecvm = 6;
    end
  elseif (irevcm == 3)
    [itn, stplhs, stprhs, anorm, sigmax, its, sigerr, ifail] = ...
       nag_sparse_complex_herm_basic_diag(work);
    if (ifail ~= 0)
      irecvm = 6;
    end
    fprintf('\nMonitoring at iteration number %d\nresidual norm: %14.4e\n', ...
            itn, stplhs);
    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, its, sigerr, ifail] = ...
     nag_sparse_complex_herm_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:     1.4937e+01
     +2.1423e-01 +      +4.5333e+00I
     -1.6589e+00 +      -1.2672e+01I
     +2.4101e+00 +      +7.4551e+00I
     +4.4400e+00 +      -6.4174e+00I
     +9.1135e+00 +      +3.7812e+00I
     +4.4419e+00 +      -4.0382e+00I
     +1.4757e+00 +      +1.2662e+00I
     +8.4872e+00 +      -3.5347e+00I
     +5.9948e+00 +      +9.6851e-01I

   Residual Vector
     -1.8370e+00 +      +3.6956e+00I
     -6.5005e-01 +      +2.5458e-01I
     -1.2616e-01 +      -1.3625e-01I
     -1.3120e-01 +      +1.4130e-01I
     -1.1471e+00 +      +7.3386e-01I
     -5.5054e-01 +      -1.0535e+00I
     +1.7165e+00 +      -1.4614e+00I
     -3.5829e-01 +      +2.8764e-01I
     -3.0278e-01 +      -3.5324e-01I

Monitoring at iteration number 4
residual norm:     1.4602e+00
     +1.0061e+00 +      +8.9847e+00I
     +1.9637e+00 +      -7.9768e+00I
     +3.0067e+00 +      +7.0285e+00I
     +3.9830e+00 +      -5.9636e+00I
     +5.0390e+00 +      +5.0432e+00I
     +6.0488e+00 +      -4.0771e+00I
     +6.9710e+00 +      +3.0168e+00I
     +8.0118e+00 +      -1.9806e+00I
     +9.0074e+00 +      +9.6458e-01I

   Residual Vector
     +1.1524e-02 +      -2.8188e-02I
     +1.3513e-02 +      -1.7345e-01I
     +1.8173e-02 +      +1.9627e-02I
     +1.8900e-02 +      -2.0354e-02I
     -9.0877e-02 +      -1.0895e-01I
     -2.3890e-01 +      +3.2440e-01I
     +1.9031e-01 +      -1.5499e-02I
     +5.1611e-02 +      -4.1435e-02I
     +4.3615e-02 +      +5.0884e-02I

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

   Solution Vector
     +1.0000e+00 +      +9.0000e+00I
     +2.0000e+00 +      -8.0000e+00I
     +3.0000e+00 +      +7.0000e+00I
     +4.0000e+00 +      -6.0000e+00I
     +5.0000e+00 +      +5.0000e+00I
     +6.0000e+00 +      -4.0000e+00I
     +7.0000e+00 +      +3.0000e+00I
     +8.0000e+00 +      -2.0000e+00I
     +9.0000e+00 +      +1.0000e+00I

   Residual Vector
     +1.3323e-14 +      -1.4211e-14I
     +0.0000e+00 +      +0.0000e+00I
     +0.0000e+00 +      +0.0000e+00I
     +0.0000e+00 +      +7.1054e-15I
     +1.4211e-14 +      +0.0000e+00I
     -7.1054e-15 +      -3.5527e-15I
     +0.0000e+00 +      +0.0000e+00I
     +0.0000e+00 +      -1.4211e-14I
     +1.4211e-14 +      +0.0000e+00I

function f11gt_example
nz = 23;
a = zeros(10000,1);
a(1:nz) = [ 6 + 0.i;
           -1 + 1.i;
            6 + 0.i;
            0 + 1.i;
            5 + 0.i;
            5 + 0.i;
            2 - 2.i;
            4 + 0.i;
            1 + 1.i;
            2 + 0.i;
            6 + 0.i;
           -4 + 3.i;
            0 + 1.i;
           -1 + 0.i;
            6 + 0.i;
           -1 - 1.i;
            0 - 1.i;
            9 + 0.i;
            1 + 3.i;
            1 + 2.i;
           -1 + 0.i;
            1 + 4.i;
            9 + 0.i];
irow = zeros(10000, 1, 'int64');
irow(1:nz) = [int64(1);2;2;3;3;4;5;5;6;6;6;7;7;7;7;8;8;8;9;9;9;9;9];
icol = zeros(10000, 1, 'int64');
icol(1:nz) = [int64(1);1;2;2;3;4;1;5;3;4;6;2;5;6;7;4;6;8;1;5;6;8;9];
lfill = int64(0);
dtol = 0;
mic = 'N';
dscale = 0;
ipiv = [int64(0);0;0;0;0;0;0;0;0];
method = 'CG    ';
precon = 'P';
n = 9;
tol = 1e-06;
maxitn = int64(20);
anorm = 0;
sigmax = 0;
maxits = int64(9);
monit = int64(2);

irevcm = int64(0);
u = [complex(0);
      0 + 0i;
      0 + 0i;
      0 + 0i;
      0 + 0i;
      0 + 0i;
      0 + 0i;
      0 + 0i;
      0 + 0i];
v = [ 8 + 54i;
      -10 - 92i;
      25 + 27i;
      26 - 28i;
      54 + 12i;
      26 - 22i;
      47 + 65i;
      71 - 57i;
      60 + 70i];
wgt = [0; 0; 0; 0; 0; 0; 0; 0; 0];


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

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

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

  if (irevcm == 1)
    [v, ifail] = f11xs(a(1:nz), irow(1:nz), icol(1:nz), 'N', u);
    if (ifail ~= 0)
      irecvm = 6;
    end
  elseif (irevcm == 2)
    [v, ifail] = f11jp(a, irow, icol, ipiv, istr, 'N', u);
    if (ifail ~= 0)
      irecvm = 6;
    end
  elseif (irevcm == 3)
    [itn, stplhs, stprhs, anorm, sigmax, its, sigerr, ifail] = f11gt(work);
    if (ifail ~= 0)
      irecvm = 6;
    end
    fprintf('\nMonitoring at iteration number %d\nresidual norm: %14.4e\n', ...
            itn, stplhs);
    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, its, sigerr, ifail] = f11gt(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:     1.4937e+01
     +2.1423e-01 +      +4.5333e+00I
     -1.6589e+00 +      -1.2672e+01I
     +2.4101e+00 +      +7.4551e+00I
     +4.4400e+00 +      -6.4174e+00I
     +9.1135e+00 +      +3.7812e+00I
     +4.4419e+00 +      -4.0382e+00I
     +1.4757e+00 +      +1.2662e+00I
     +8.4872e+00 +      -3.5347e+00I
     +5.9948e+00 +      +9.6851e-01I

   Residual Vector
     -1.8370e+00 +      +3.6956e+00I
     -6.5005e-01 +      +2.5458e-01I
     -1.2616e-01 +      -1.3625e-01I
     -1.3120e-01 +      +1.4130e-01I
     -1.1471e+00 +      +7.3386e-01I
     -5.5054e-01 +      -1.0535e+00I
     +1.7165e+00 +      -1.4614e+00I
     -3.5829e-01 +      +2.8764e-01I
     -3.0278e-01 +      -3.5324e-01I

Monitoring at iteration number 4
residual norm:     1.4602e+00
     +1.0061e+00 +      +8.9847e+00I
     +1.9637e+00 +      -7.9768e+00I
     +3.0067e+00 +      +7.0285e+00I
     +3.9830e+00 +      -5.9636e+00I
     +5.0390e+00 +      +5.0432e+00I
     +6.0488e+00 +      -4.0771e+00I
     +6.9710e+00 +      +3.0168e+00I
     +8.0118e+00 +      -1.9806e+00I
     +9.0074e+00 +      +9.6458e-01I

   Residual Vector
     +1.1524e-02 +      -2.8188e-02I
     +1.3513e-02 +      -1.7345e-01I
     +1.8173e-02 +      +1.9627e-02I
     +1.8900e-02 +      -2.0354e-02I
     -9.0877e-02 +      -1.0895e-01I
     -2.3890e-01 +      +3.2440e-01I
     +1.9031e-01 +      -1.5499e-02I
     +5.1611e-02 +      -4.1435e-02I
     +4.3615e-02 +      +5.0884e-02I

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

   Solution Vector
     +1.0000e+00 +      +9.0000e+00I
     +2.0000e+00 +      -8.0000e+00I
     +3.0000e+00 +      +7.0000e+00I
     +4.0000e+00 +      -6.0000e+00I
     +5.0000e+00 +      +5.0000e+00I
     +6.0000e+00 +      -4.0000e+00I
     +7.0000e+00 +      +3.0000e+00I
     +8.0000e+00 +      -2.0000e+00I
     +9.0000e+00 +      +1.0000e+00I

   Residual Vector
     +1.3323e-14 +      +7.1054e-15I
     +3.5527e-15 +      +0.0000e+00I
     +3.5527e-15 +      +0.0000e+00I
     +0.0000e+00 +      +7.1054e-15I
     +7.1054e-15 +      +7.1054e-15I
     -7.1054e-15 +      +0.0000e+00I
     -7.1054e-15 +      +0.0000e+00I
     +0.0000e+00 +      +0.0000e+00I
     +1.4211e-14 +      +0.0000e+00I


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–2013