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_real_gen_basic_diag (f11bf)

▸▿ Contents

    1  Purpose
    2  Syntax
    3  Description
    4  References
▸▿ 5  Parameters
    6  Error Indicators and Warnings
    7  Accuracy
    8  Further Comments
    9  Example

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

Optional Input Parameters

1:     lwork – int64int32nag_int scalar
Default: the dimension of the array work.
The dimension of the array work (see also Arguments in nag_sparse_real_gen_basic_setup (f11bd)).
Constraint: lwork≥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 Arguments in nag_sparse_real_gen_basic_setup (f11bd)).

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 in the previous call to nag_sparse_real_gen_basic_setup (f11bd), then anorm contains Ap, where p=1, 2 or ∞, either supplied or, in the case of 1 or ∞, estimated by nag_sparse_real_gen_basic_solver (f11be); otherwise anorm=0.0.
5:     sigmax – double scalar
If iterm=2 in the previous call to nag_sparse_real_gen_basic_setup (f11bd), the current estimate of the largest singular value σ1A- 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 Description and Arguments in nag_sparse_real_gen_basic_setup (f11bd)); otherwise, sigmax=0.0 is returned.
6:     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_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 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_real_gen_basic_setup (f11bd).

Open in the MATLAB editor: f11bf_example

function f11bf_example


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

% Solve sparse system Ax = b iteratively using ILU preconditioner

% Define sparse matrix A and RHS B
n    = int64(8);
nz   = int64(24);
a    = zeros(3*nz, 1);
irow = zeros(3*nz, 1, 'int64');
icol = irow;
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]);
a(1:nz)    = [2;-1; 1; 4;-3; 2;-7; 2; 3;-4; 5; 5;
             -1; 8;-3;-6; 5; 2;-5;-1; 6;-1; 2; 3];
b          = [6; 8;-9;46;17;21;22;34];

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

% Iterative Solution Setup
%      Input parameters
method = 'BICGSTAB';
precon = 'Preconditioned';
lpoly  = int64(1);
tol    = sqrt(x02aj);
maxitn = int64(20);
anorm  = 0;
sigmax = 0;
monit  = int64(1);
lwork  = int64(6000);
% Setup iterative method
[lwreq, work, ifail] = ...
  f11bd(...
        method, precon, n, lpoly, tol, maxitn, anorm, sigmax, ...
        monit, lwork, 'norm_p', '1');

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

while (irevcm ~= 4)

  [irevcm, u, v, work, ifail] = f11be(...
                                      irevcm, u, v, wgt, work);

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



f11bf example results


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

   Solution Vector  Residual Vector
         -4.5858         1.53e+01
          1.0154         2.66e+01
         -2.2234        -8.75e+00
          6.0097         1.86e+01
          1.3827         8.28e+00
         -7.9070         2.04e+01
          0.4427         9.61e+00
          5.9248         3.31e+01

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

   Solution Vector  Residual Vector
          4.1642        -2.96e+00
          4.9370        -5.55e+00
          4.8101         8.21e-01
          5.4324        -1.68e+01
          5.8531         5.60e-01
         11.9250        -1.91e+00
          8.4826         1.01e+00
          6.0625        -3.10e+00

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

   Solution Vector  Residual Vector
          1.0000        -1.36e-09
          2.0000        -2.61e-09
          3.0000         2.25e-10
          4.0000        -3.22e-09
          5.0000         6.30e-10
          6.0000        -5.24e-10
          7.0000         9.58e-10
          8.0000        -8.49e-10
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