NAG Toolbox: nag_sparse_complex_gen_precon_ilu_solve (f11dp)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{trans}$ – string (length ≥ 1)

Specifies whether or not the matrix $M$ is transposed.

$\mathbf{trans}=\text{'N'}$

$Mx=y$ is solved.

$\mathbf{trans}=\text{'T'}$

$M^{\mathrm{T}}x=y$ is solved.

Constraint: $\mathbf{trans}=\text{'N'}$ or $\text{'T'}$.

2:     $\mathrm{a}\left(\mathbf{la}\right)$ – complex array

The values returned in the array a by a previous call to nag_sparse_complex_gen_precon_ilu (f11dn).

3:     $\mathrm{irow}\left(\mathbf{la}\right)$ – int64int32nag_int array

4:     $\mathrm{icol}\left(\mathbf{la}\right)$ – int64int32nag_int array

5:     $\mathrm{ipivp}\left(\mathbf{n}\right)$ – int64int32nag_int array

6:     $\mathrm{ipivq}\left(\mathbf{n}\right)$ – int64int32nag_int array

7:     $\mathrm{istr}\left(\mathbf{n}+1\right)$ – int64int32nag_int array

8:     $\mathrm{idiag}\left(\mathbf{n}\right)$ – int64int32nag_int array

The values returned in arrays irow, icol, ipivp, ipivq, istr and idiag by a previous call to nag_sparse_complex_gen_precon_ilu (f11dn).

9:     $\mathrm{check}$ – string (length ≥ 1)

Specifies whether or not the CS representation of the matrix $M$ should be checked.

$\mathbf{check}=\text{'C'}$

Checks are carried on the values of n, irow, icol, ipivp, ipivq, istr and idiag.

$\mathbf{check}=\text{'N'}$

None of these checks are carried out.

See also Use of check.

Constraint: $\mathbf{check}=\text{'C'}$ or $\text{'N'}$.

10:   $\mathrm{y}\left(\mathbf{n}\right)$ – complex array

The right-hand side vector $y$.

Optional Input Parameters

1:     $\mathrm{n}$ – int64int32nag_int scalar

Default: the dimension of the arrays ipivp, ipivq, idiag, y. (An error is raised if these dimensions are not equal.)

$n$, the order of the matrix $M$. This must be the same value as was supplied in the preceding call to nag_sparse_complex_gen_precon_ilu (f11dn).

Constraint: $\mathbf{n}\ge 1$.

2:     $\mathrm{la}$ – int64int32nag_int scalar

Default: the dimension of the arrays a, irow, icol. (An error is raised if these dimensions are not equal.)

The dimension of the arrays a, irow and icol. this must be the same value supplied in the preceding call to nag_sparse_complex_gen_precon_ilu (f11dn).

Output Parameters

1:     $\mathrm{x}\left(\mathbf{n}\right)$ – complex array

The solution vector $x$.

2:     $\mathrm{ifail}$ – int64int32nag_int scalar

$\mathbf{ifail}=\mathbf{0}$ unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

   $\mathbf{ifail}=1$

On entry,	$\mathbf{trans}\ne \text{'N'}$ or $\text{'T'}$,
or	$\mathbf{check}\ne \text{'C'}$ or $\text{'N'}$.

   $\mathbf{ifail}=2$

On entry,

$\mathbf{n}<1$.

   $\mathbf{ifail}=3$

On entry, the CS representation of the preconditioning matrix $M$ is invalid. Further details are given in the error message. Check that the call to nag_sparse_complex_gen_precon_ilu_solve (f11dp) has been preceded by a valid call to nag_sparse_complex_gen_precon_ilu (f11dn) and that the arrays a, irow, icol, ipivp, ipivq, istr and idiag have not been corrupted between the two calls.

   $\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.

Accuracy

Further Comments

Timing

Use of check

Example

Open in the MATLAB editor: f11dp_example

function f11dp_example


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

% Solve sparse system Ax = b using complete LU decomposition

% Define sparse matrix A and RHS B
n    = int64(4);
nz   = int64(11);
a    = zeros(3*nz, 1);
irow = zeros(3*nz, 1, 'int64');
icol = irow;
sparseA = [  1  2    1    2;
             1  3    1    3;
            -1 -3    2    1;
             2  0    2    3;
             0  4    2    4;
             3  4    3    1;
            -2  0    3    4;
             1 -1    4    1;
            -2 -1    4    2;
             1  0    4    3;
             1  3    4    4];
a(1:nz)    = sparseA(:,1) + i*sparseA(:,2);
irow(1:nz) = int64(sparseA(:,3));
icol(1:nz) = int64(sparseA(:,4));

b          = [ 5 + 14i;
              21 +  5i;
             -21 + 18i;
              14 +  4i];

% ILU preconditioner
%     Input parameters
lfill = int64(-1);
dtol  = 0;
milu  = 'No modification';
ipivp = zeros(n, 1, 'int64');
ipivq = zeros(n, 1, 'int64');
% Compute complete factorization
[a, irow, icol, ipivp, ipivq, istr, idiag, nnzc, npivm, ifail] = ...
    f11dn(...
          nz, a, irow, icol, lfill, dtol, milu, ipivp, ipivq);

% Check whether factorization is complete
if npivm>0
  error('Factorization is not complete');
end

% Solution Setup
%      Input parameters
[x, ifail] = f11dp( ...
                    'N', a, irow, icol, ipivp, ipivq, istr, idiag, 'C', b);

disp('Solution of linear system');
disp(x);

f11dp example results

Solution of linear system
   1.0000 + 4.0000i
   2.0000 + 3.0000i
   3.0000 - 2.0000i
   4.0000 - 1.0000i