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

 Contents

    1  Purpose
    2  Syntax
    7  Accuracy
    9  Example

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:     worklwork – complex array
The array work as returned by nag_sparse_complex_gen_basic_solver (f11bs) (see also Description and Arguments in nag_sparse_complex_gen_basic_solver (f11bs)).

Optional Input Parameters

1:     lwork int64int32nag_int scalar
Default: the dimension of the array work.
The dimension of the array work (see also nag_sparse_complex_gen_basic_setup (f11br)).
Constraint: lwork120.
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)).

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 in the previous call to nag_sparse_complex_gen_basic_setup (f11br), then anorm contains Ap, where p=1, 2 or , either supplied or, in the case of 1 or , estimated by nag_sparse_complex_gen_basic_solver (f11bs); otherwise anorm=0.0.
5:     sigmax – double scalar
If iterm=2 in the previous call to nag_sparse_complex_gen_basic_setup (f11br), the current estimate of the largest singular value σ1A- 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 Description and Arguments in nag_sparse_complex_gen_basic_setup (f11br)); otherwise, sigmax=0.0 is returned.
6:     worklwork – complex array
Communication array, used to store information between calls to nag_sparse_complex_gen_basic_diag (f11bt).
7:     ifail int64int32nag_int scalar
ifail=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
If 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.
   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 or 4.
   ifail=-99
An unexpected error has been triggered by this routine. Please contact NAG.
   ifail=-399
Your licence key may have expired or may not have been installed correctly.
   ifail=-999
Dynamic memory allocation failed.

Accuracy

Not applicable.

Further Comments

None.

Example

See Example in nag_sparse_complex_gen_basic_setup (f11br).
function f11bt_example


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

% Solve sparse system Ax = b iteratively using ILU preconditioner

% Define sparse matrix A and RHS B
nz   = int64(24);
n    = int64(8);
a    = complex(zeros(3*nz,1));
irow = zeros(3*nz,1,'int64');
icol = zeros(3*nz,1,'int64');
a(1:nz) = [ 2 + 1i, -1 + 1i,  1 - 3i,  4 + 7i, -3 + 0i,  2 + 4i, ...
           -7 - 5i,  2 + 1i,  3 + 2i, -4 + 2i,  0 + 1i,  5 - 3i, ...
           -1 + 2i,  8 + 6i, -3 - 4i, -6 - 2i,  5 - 2i,  2 + 0i, ...
            0 - 5i, -1 + 5i,  6 + 2i, -1 + 4i,  2 + 0i,  3 + 3i];
b       = [ 7 + 11i;
            1 + 24i;
          -13 - 18i;
          -10 +  3i;
           23 + 14i;
           17 -  7i;
           15 -  3i;
           -3 + 20i];
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]);

% 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] = ...
    f11dn(...
          nz, a, irow, icol, lfill, dtol, milu, ipivp, ipivq);


% Iterative Solution Setup
%      Input parameters
method = 'TFQMR   ';
precon = 'P';
lpoly  = int64(1);
tol    = sqrt(x02aj);
maxitn = int64(20);
anorm  = 0;
sigmax = 0;
monit  = int64(2);
lwork  = int64(6000);

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

irevcm = int64(0);
wgt    = zeros(n,1);
u      = complex(zeros(n,1));
v      = b;

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

  if (irevcm == -1)
    % v = A^Hu
    [v, ifail] = f11xn(...
                       'T', a(1:nz), irow(1:nz), icol(1:nz), 'N', u);
  elseif (irevcm == 1)
    % v = Au
    [v, ifail] = f11xn(...
                       'N', a(1:nz), irow(1:nz), icol(1:nz), 'N', u);
  elseif (irevcm == 2)
    % Solve ILU v = u  
    [v, ifail] = f11dp(...
                       'N', a, irow, icol, ipivp, ipivq, istr, idiag, 'N', u);
  elseif (irevcm == 3)
    % Monitoring stage
    [itn, stplhs, stprhs, anorm, sigmax, work, ifail] = ...
       f11bt(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, work, ifail] = ...
      f11bt(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);


f11bt example results


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

   Solution Vector
   0.6905 + 1.4236i
   0.0739 - 1.1880i
   1.4778 + 0.4785i
   5.6572 - 3.0786i
   1.4243 - 1.1246i
   0.1037 + 1.9740i
   0.4498 - 1.2715i
   2.5704 + 1.7578i


   Residual Vector
   1.7772 + 4.6797i
   1.0774 + 6.4600i
  -3.2812 -11.3135i
  -3.8698 - 1.6438i
   8.9912 +11.1004i
   9.7428 - 0.4622i
   3.1668 + 2.8721i
 -10.3231 + 1.5837i


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

   Solution Vector
   1.0000 + 1.0000i
   2.0000 - 1.0000i
   3.0000 + 1.0000i
   4.0000 - 1.0000i
   3.0000 - 1.0000i
   2.0000 + 1.0000i
   1.0000 - 1.0000i
  -0.0000 + 3.0000i


   Residual Vector
   1.0e-11 *

  -0.0060 - 0.0782i
   0.1551 - 0.1364i
   0.0822 + 0.0703i
   0.0988 - 0.0218i
  -0.1254 - 0.0417i
  -0.0735 + 0.0527i
   0.0284 + 0.0162i
   0.1112 + 0.2416i


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