PDF version (NAG web site
, 64bit version, 64bit version)
NAG Toolbox: nag_sparse_complex_gen_precon_ilu (f11dn)
Purpose
nag_sparse_complex_gen_precon_ilu (f11dn) computes an incomplete
$LU$ factorization of a complex sparse nonHermitian matrix, represented in coordinate storage format. This factorization may be used as a preconditioner in combination with
nag_sparse_complex_gen_basic_solver (f11bs) or
nag_sparse_complex_gen_solve_ilu (f11dq).
Syntax
[
a,
irow,
icol,
ipivp,
ipivq,
istr,
idiag,
nnzc,
npivm,
ifail] = f11dn(
nz,
a,
irow,
icol,
lfill,
dtol,
milu,
ipivp,
ipivq, 'n',
n, 'la',
la, 'pstrat',
pstrat)
[
a,
irow,
icol,
ipivp,
ipivq,
istr,
idiag,
nnzc,
npivm,
ifail] = nag_sparse_complex_gen_precon_ilu(
nz,
a,
irow,
icol,
lfill,
dtol,
milu,
ipivp,
ipivq, 'n',
n, 'la',
la, 'pstrat',
pstrat)
Description
nag_sparse_complex_gen_precon_ilu (f11dn) computes an incomplete
$LU$ factorization (see
Meijerink and Van der Vorst (1977) and
Meijerink and Van der Vorst (1981)) of a complex sparse nonHermitian
$n$ by
$n$ matrix
$A$. The factorization is intended primarily for use as a preconditioner with one of the iterative solvers
nag_sparse_complex_gen_basic_solver (f11bs) or
nag_sparse_complex_gen_solve_ilu (f11dq).
The decomposition is written in the form
where
and
$L$ is lower triangular with unit diagonal elements,
$D$ is diagonal,
$U$ is upper triangular with unit diagonals,
$P$ and
$Q$ are permutation matrices, and
$R$ is a remainder matrix.
The amount of fillin occurring in the factorization can vary from zero to complete fill, and can be controlled by specifying either the maximum level of fill
lfill, or the drop tolerance
dtol.
The argument
pstrat defines the pivoting strategy to be used. The options currently available are no pivoting, userdefined pivoting, partial pivoting by columns for stability, and complete pivoting by rows for sparsity and by columns for stability. The factorization may optionally be modified to preserve the rowsums of the original matrix.
The sparse matrix
$A$ is represented in coordinate storage (CS) format (see
Coordinate storage (CS) format in the F11 Chapter Introduction). The array
a stores all the nonzero elements of the matrix
$A$, while arrays
irow and
icol store the corresponding row and column indices respectively. Multiple nonzero elements may not be specified for the same row and column index.
The preconditioning matrix
$M$ is returned in terms of the CS representation of the matrix
Further algorithmic details are given in
Algorithmic Details.
References
Meijerink J and Van der Vorst H (1977) An iterative solution method for linear systems of which the coefficient matrix is a symmetric Mmatrix Math. Comput. 31 148–162
Meijerink J and Van der Vorst H (1981) Guidelines for the usage of incomplete decompositions in solving sets of linear equations as they occur in practical problems J. Comput. Phys. 44 134–155
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 Fillin). 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 fillin (see
Control of Fillin); 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 rowsums (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 userdefined 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
Errors or warnings detected by the function:
 ${\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(i1\right)<{\mathbf{irow}}\left(i\right)$, or ${\mathbf{irow}}\left(i1\right)={\mathbf{irow}}\left(i\right)$ and ${\mathbf{icol}}\left(i1\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 fillin 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
The accuracy of the factorization will be determined by the size of the elements that are dropped and the size of any modifications made to the pivot elements. If these sizes are small then the computed factors will correspond to a matrix close to
$A$. The factorization can generally be made more accurate by increasing
lfill, or by reducing
dtol with
${\mathbf{lfill}}<0$.
If
nag_sparse_complex_gen_precon_ilu (f11dn) is used in combination with
nag_sparse_complex_gen_basic_solver (f11bs) or
nag_sparse_complex_gen_solve_ilu (f11dq), the more accurate the factorization the fewer iterations will be required. However, the cost of the decomposition will also generally increase.
Further Comments
Timing
The time taken for a call to nag_sparse_complex_gen_precon_ilu (f11dn) is roughly proportional to ${{\mathbf{nnzc}}}^{2}/{\mathbf{n}}$.
Control of Fillin
If
${\mathbf{lfill}}\ge 0$ the amount of fillin occurring in the incomplete factorization is controlled by limiting the maximum level of fillin to
lfill. The original nonzero elements of
$A$ are defined to be of level
$0$. The fill level of a new nonzero location occurring during the factorization is defined as:
where
${k}_{\mathrm{e}}$ is the level of fill of the element being eliminated, and
${k}_{\mathrm{c}}$ is the level of fill of the element causing the fillin.
If
${\mathbf{lfill}}<0$ the fillin is controlled by means of the drop tolerance
dtol. A potential fillin element
${a}_{ij}$ occurring in row
$i$ and column
$j$ will not be included if:
where
$\alpha $ is the maximum modulus element in the matrix
$A$.
For either method of control, any elements which are not included are discarded unless
${\mathbf{milu}}=\text{'M'}$, in which case their contributions are subtracted from the pivot element in the relevant elimination row, to preserve the rowsums of the original matrix.
Should the factorization process break down a local restart process is implemented as described in
Algorithmic Details. This will affect the amount of fill present in the final factorization.
Algorithmic Details
The factorization is constructed row by row. At each elimination stage a row index is chosen. In the case of complete pivoting this index is chosen in order to reduce fillin. Otherwise the rows are treated in the order given, or some userdefined order.
The chosen row is copied from the original matrix
$A$ and modified according to those previous elimination stages which affect it. During this process any fillin elements are either dropped or kept according to the values of
lfill or
dtol. In the case of a modified factorization (
${\mathbf{milu}}=\text{'M'}$) the sum of the dropped terms for the given row is stored.
Finally the pivot element for the row is chosen and the multipliers are computed for this elimination stage. For partial or complete pivoting the pivot element is chosen in the interests of stability as the element of largest absolute value in the row. Otherwise the pivot element is chosen in the order given, or some userdefined order.
If the factorization breaks down because the chosen pivot element is zero, or there is no nonzero pivot available, a local restart recovery process is implemented. The modification of the given pivot row according to previous elimination stages is repeated, but this time keeping all fillin. Note that in this case the final factorization will include more fill than originally specified by the usersupplied value of
lfill or
dtol. The local restart usually results in a suitable nonzero pivot arising. The original criteria for dropping fillin elements is then resumed for the next elimination stage (hence the
local nature of the restart process). Should this restart process also fail to produce a nonzero pivot element an arbitrary unit pivot is introduced in an arbitrarily chosen column.
nag_sparse_complex_gen_precon_ilu (f11dn) returns an integer argument
npivm which gives the number of these arbitrary unit pivots introduced. If no pivots were modified but local restarts occurred
${\mathbf{npivm}}=1$ is returned.
Choice of Arguments
There is unfortunately no choice of the various algorithmic arguments which is optimal for all types of matrix, and some experimentation will generally be required for each new type of matrix encountered. The recommended approach is to start with
${\mathbf{lfill}}=0$ and
${\mathbf{pstrat}}=\text{'C'}$. If the value returned for
npivm is significantly larger than zero, i.e., a large number of pivot modifications were required to ensure that
$M$ existed, the preconditioner is not likely to be satisfactory. In this case increase
lfill until
npivm falls to a value close to zero.
For certain classes of matrices (typically those arising from the discretization of elliptic or parabolic partial differential equations) the convergence rate of the preconditioned iterative solver can sometimes be significantly improved by using an incomplete factorization which preserves the rowsums of the original matrix. In these cases try setting ${\mathbf{milu}}=\text{'M'}$.
Direct Solution of Sparse Linear Systems
Although it is not the primary purpose of the functions
nag_sparse_complex_gen_precon_ilu (f11dn) and
nag_sparse_complex_gen_precon_ilu_solve (f11dp), they may be used together to obtain a
direct solution to a nonsingular sparse complex nonHermitian linear system. To achieve this the call to
nag_sparse_complex_gen_precon_ilu_solve (f11dp) should be preceded by a
complete $LU$ factorization
A complete factorization is obtained from a call to
nag_sparse_complex_gen_precon_ilu (f11dn) with
${\mathbf{lfill}}<0$ and
${\mathbf{dtol}}=0.0$, provided
${\mathbf{npivm}}\le 0$ on exit. A positive value of
npivm indicates that
$A$ is singular, or illconditioned. A factorization with positive
npivm may serve as a preconditioner, but will not result in a direct solution. It is therefore
essential to check the output value of
npivm if a direct solution is required.
The use of
nag_sparse_complex_gen_precon_ilu (f11dn) and
nag_sparse_complex_gen_precon_ilu_solve (f11dp) as a direct method is illustrated in
nag_sparse_complex_gen_precon_ilu_solve (f11dp).
Example
This example reads in a complex sparse nonHermitian matrix $A$ and calls nag_sparse_complex_gen_precon_ilu (f11dn) to compute an incomplete $LU$ factorization. It then outputs the nonzero elements of both $A$ and $C=L+{D}^{1}+U2I$.
The call to nag_sparse_complex_gen_precon_ilu (f11dn) has ${\mathbf{lfill}}=0$, and ${\mathbf{pstrat}}=\text{'C'}$, giving an unmodified zerofill $LU$ factorization, with row pivoting for sparsity and column pivoting for stability.
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]);
[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
PDF version (NAG web site
, 64bit version, 64bit version)
© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2015