NAG Toolbox: nag_sparse_complex_gen_precon_ilu (f11dn)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

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

The number of nonzero elements in the matrix $A$.

Constraint: $1\le \mathbf{nz}\le {\mathbf{n}}^2$.

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

The nonzero elements in the matrix $A$, ordered by increasing row index, and by increasing column index within each row. Multiple entries for the same row and column indices are not permitted. The function nag_sparse_complex_gen_sort (f11zn) may be used to order the elements in this way.

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

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

The row and column indices of the nonzero elements supplied in a.

Constraints:

irow and icol must satisfy these constraints (which may be imposed by a call to nag_sparse_complex_gen_sort (f11zn)):

• $1\le \mathbf{irow}\left(\mathit{i}\right)\le \mathbf{n}$ and $1\le \mathbf{icol}\left(\mathit{i}\right)\le \mathbf{n}$, for $\mathit{i}=1,2,\dots ,\mathbf{nz}$;
• either $\mathbf{irow}\left(\mathit{i}-1\right)<\mathbf{irow}\left(\mathit{i}\right)$ or both $\mathbf{irow}\left(\mathit{i}-1\right)=\mathbf{irow}\left(\mathit{i}\right)$ and $\mathbf{icol}\left(\mathit{i}-1\right)<\mathbf{icol}\left(\mathit{i}\right)$, for $\mathit{i}=2,3,\dots ,\mathbf{nz}$.

5:     $\mathrm{lfill}$ – int64int32nag_int scalar

If $\mathbf{lfill}\ge 0$ its value is the maximum level of fill allowed in the decomposition (see Control of Fill-in). A negative value of lfill indicates that dtol will be used to control the fill instead.

6:     $\mathrm{dtol}$ – double scalar

If $\mathbf{lfill}<0$, dtol is used as a drop tolerance to control the fill-in (see Control of Fill-in); otherwise dtol is not referenced.

Constraint: if $\mathbf{lfill}<0$, $\mathbf{dtol}\ge 0.0$.

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

Indicates whether or not the factorization should be modified to preserve row-sums (see Choice of s).

$\mathbf{milu}=\text{'M'}$

The factorization is modified.

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

The factorization is not modified.

Constraint: $\mathbf{milu}=\text{'M'}$ or $\text{'N'}$.

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

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

If $\mathbf{pstrat}=\text{'U'}$, then $\mathbf{ipivp}\left(k\right)$ and $\mathbf{ipivq}\left(k\right)$ must specify the row and column indices of the element used as a pivot at elimination stage $k$. Otherwise ipivp and ipivq need not be initialized.

Constraint: if $\mathbf{pstrat}=\text{'U'}$, ipivp and ipivq must both hold valid permutations of the integers on [1,n].

Optional Input Parameters

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

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

$n$, the order of the matrix $A$.

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. these arrays must be of sufficient size to store both $A$ (nz elements) and $C$ (nnzc elements).

Constraint: $\mathbf{la}\ge 2\times \mathbf{nz}$.

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

Default: $\text{'C'}$

Specifies the pivoting strategy to be adopted.

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

No pivoting is carried out.

$\mathbf{pstrat}=\text{'U'}$

Pivoting is carried out according to the user-defined input values of ipivp and ipivq.

$\mathbf{pstrat}=\text{'P'}$

Partial pivoting by columns for stability is carried out.

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

Complete pivoting by rows for sparsity, and by columns for stability, is carried out.

Constraint: $\mathbf{pstrat}=\text{'N'}$, $\text{'U'}$, $\text{'P'}$ or $\text{'C'}$.

Output Parameters

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

The first nz entries of a contain the nonzero elements of $A$ and the next nnzc entries contain the elements of the matrix $C$. Matrix elements are ordered by increasing row index, and by increasing column index within each row.

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

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

The row and column indices of the nonzero elements returned in a.

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

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

The pivot indices. If $\mathbf{ipivp}\left(k\right)=i$ and $\mathbf{ipivq}\left(k\right)=j$ then the element in row $i$ and column $j$ was used as the pivot at elimination stage $k$.

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

$\mathbf{istr}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{n}$, is the starting address in the arrays a, irow and icol of row $i$ of the matrix $C$. $\mathbf{istr}\left(\mathbf{n}+1\right)$ is the address of the last nonzero element in $C$ plus one.

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

$\mathbf{idiag}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{n}$, holds the index of arrays a, irow and icol which holds the diagonal element in row $i$ of the matrix $C$.

8:     $\mathrm{nnzc}$ – int64int32nag_int scalar

The number of nonzero elements in the matrix $C$.

9:     $\mathrm{npivm}$ – int64int32nag_int scalar

If $\mathbf{npivm}>0$ it gives the number of pivots which were modified during the factorization to ensure that $M$ exists.

If $\mathbf{npivm}=-1$ no pivot modifications were required, but a local restart occurred (see Algorithmic Details). The quality of the preconditioner will generally depend on the returned value of npivm.

If npivm is large the preconditioner may not be satisfactory. In this case it may be advantageous to call nag_sparse_complex_gen_precon_ilu (f11dn) again with an increased value of lfill, a reduced value of dtol, or set $\mathbf{pstrat}=\text{'C'}$. See also Direct Solution of Sparse Linear Systems.

10:   $\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{n}<1$,
or	$\mathbf{nz}<1$,
or	$\mathbf{nz}>{\mathbf{n}}^2$,
or	$\mathbf{la}<2\times \mathbf{nz}$,
or	$\mathbf{lfill}<0$ and $\mathbf{dtol}<0.0$,
or	$\mathbf{pstrat}\ne \text{'N'}$, $\text{'U'}$, $\text{'P'}$ or $\text{'C'}$,
or	$\mathbf{milu}\ne \text{'M'}$ or $\text{'N'}$,
or	$\mathit{liwork}<7\times \mathbf{n}+2$.

   $\mathbf{ifail}=2$

On entry, the arrays irow and icol fail to satisfy the following constraints:

• $1\le \mathbf{irow}\left(i\right)\le \mathbf{n}$ and $1\le \mathbf{icol}\left(i\right)\le \mathbf{n}$, for $i=1,2,\dots ,\mathbf{nz}$;
• $\mathbf{irow}\left(i-1\right)<\mathbf{irow}\left(i\right)$, or $\mathbf{irow}\left(i-1\right)=\mathbf{irow}\left(i\right)$ and $\mathbf{icol}\left(i-1\right)<\mathbf{icol}\left(i\right)$, for $i=2,3,\dots ,\mathbf{nz}$.

Therefore a nonzero element has been supplied which does not lie within the matrix $A$, is out of order, or has duplicate row and column indices. Call nag_sparse_complex_gen_sort (f11zn) to reorder and sum or remove duplicates.

   $\mathbf{ifail}=3$

On entry, $\mathbf{pstrat}=\text{'U'}$, but one or both of ipivp and ipivq does not represent a valid permutation of the integers in [1,n]. An input value of ipivp or ipivq is either out of range or repeated.

   $\mathbf{ifail}=4$

la is too small, resulting in insufficient storage space for fill-in elements. The decomposition has been terminated before completion. Either increase la or reduce the amount of fill by reducing lfill, or increasing dtol.

   $\mathbf{ifail}=5$ (nag_sparse_complex_gen_sort (f11zn))

A serious error has occurred in an internal call to the specified function. Check all function calls and array sizes. Seek expert help.

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

Control of Fill-in

Algorithmic Details

Choice of Arguments

Direct Solution of Sparse Linear Systems

Example

Open in the MATLAB editor: f11dn_example

function f11dn_example


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

nz = int64(11);
n  = int64(4);
a  = zeros(2*nz, 1);
irow = zeros(2*nz, 1, 'int64');
icol = zeros(2*nz, 1, 'int64');
a(1:nz) = [ 1 + 3i; 1 + 0i; -1 - 2i; 2 - 2i; 2 + 1i; 0 + 5i;
           -2 + 0i; 1 + 1i; -2 + 4i; 1 - 3i; 0 + 7i];
irow(1:nz) = int64([1; 1; 2; 2; 2; 3; 3; 4; 4; 4; 4]);
icol(1:nz) = int64([2; 3; 1; 3; 4; 1; 4; 1; 2; 3; 4]);

lfill = int64(0);
dtol  = 0;
milu  = 'N';
ipivp = int64([0;0;0;0]);
ipivq = int64([0;0;0;0]);
% Calculate incomplete LU factorization
[a, irow, icol, ipivp, ipivq, istr, idiag, nnzc, npivm, ifail] = ...
    f11dn(...
        nz, a, irow, icol, lfill, dtol, milu, ipivp, ipivq);

fprintf('\nOriginal Matrix\n');
fprintf(' n = %d\n nz = %d\n', n, nz);
A = sparse(double(irow(1:nz)),double(icol(1:nz)),a(1:nz));
disp(A);

fprintf('\nFactorization\n');
fprintf(' n = %d\n nz = %d\n nvipm = %d\n', n, nnzc, npivm);
ifac = nz+1:nz+nnzc;
A = sparse(double(irow(ifac)),double(icol(ifac)),a(ifac));
disp(A);

fprintf('\n         i       ipivp(i)  ipivq(i)\n');
for i=1:n
  fprintf('%10i%10i%10i\n', i, ipivp(i), ipivq(i));
end

f11dn example results


Original Matrix
 n = 4
 nz = 11
   (2,1)     -1.0000 - 2.0000i
   (3,1)      0.0000 + 5.0000i
   (4,1)      1.0000 + 1.0000i
   (1,2)      1.0000 + 3.0000i
   (4,2)     -2.0000 + 4.0000i
   (1,3)      1.0000 + 0.0000i
   (2,3)      2.0000 - 2.0000i
   (4,3)      1.0000 - 3.0000i
   (2,4)      2.0000 + 1.0000i
   (3,4)     -2.0000 + 0.0000i
   (4,4)      0.0000 + 7.0000i


Factorization
 n = 4
 nz = 11
 nvipm = 0
   (1,1)      0.1000 - 0.3000i
   (4,1)      1.0000 + 1.0000i
   (2,2)      0.0000 - 0.2000i
   (3,2)     -0.4000 + 0.2000i
   (4,2)      0.2000 - 0.2000i
   (1,3)      0.1000 - 0.3000i
   (3,3)      0.2500 + 0.2500i
   (4,3)      1.0000 - 1.0000i
   (2,4)      0.0000 + 0.4000i
   (3,4)     -0.0500 + 0.6500i
   (4,4)     -0.0480 - 0.1397i


         i       ipivp(i)  ipivq(i)
         1         1         2
         2         3         1
         3         2         3
         4         4         4