Integer type:** int32**** int64**** nag_int** show int32 show int32 show int64 show int64 show nag_int show nag_int

nag_sparse_real_gen_precon_ilu (f11da) computes an incomplete LU$LU$ factorization of a real sparse nonsymmetric matrix, represented in coordinate storage format. This factorization may be used as a preconditioner in combination with nag_sparse_real_gen_basic_solver (f11be) or nag_sparse_real_gen_solve_ilu (f11dc).

nag_sparse_real_gen_precon_ilu (f11da) computes an incomplete LU$LU$ factorization (see Meijerink and Van der Vorst (1977) and Meijerink and Van der Vorst (1981)) of a real sparse nonsymmetric n$n$ by n$n$ matrix A$A$. The factorization is intended primarily for use as a preconditioner with one of the iterative solvers nag_sparse_real_gen_basic_solver (f11be) or nag_sparse_real_gen_solve_ilu (f11dc).

The decomposition is written in the form

where

and L$L$ is lower triangular with unit diagonal elements, D$D$ is diagonal, U$U$ is upper triangular with unit diagonals, P$P$ and Q$Q$ are permutation matrices, and R$R$ is a remainder matrix.

A = M + R
$$A=M+R$$ |

M = PLDUQ
$$M=PLDUQ$$ |

The amount of fill-in 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 parameter pstrat defines the pivoting strategy to be used. The options currently available are no pivoting, user-defined 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 row-sums of the original matrix.

The sparse matrix A$A$ is represented in coordinate storage (CS) format (see Section [Coordinate storage (CS) format] in the F11 Chapter Introduction). The array a stores all the nonzero elements of the matrix A$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$M$ is returned in terms of the CS representation of the matrix

Further algorithmic details are given in Section [Algorithmic Details].

C = L + D ^{ − 1} + U − 2I.
$$C=L+{D}^{-1}+U-2I\text{.}$$ |

Meijerink J and Van der Vorst H (1977) An iterative solution method for linear systems of which the coefficient matrix is a symmetric M-matrix *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

Salvini S A and Shaw G J (1996) An evaluation of new NAG Library solvers for large sparse unsymmetric linear systems *NAG Technical Report TR2/96*

- 1: nnz – int64int32nag_int scalar
- The number of nonzero elements in the matrix A$A$.
- 2: a(la) – double array
- la, the dimension of the array, must satisfy the constraint la ≥ 2 × nnz${\mathbf{la}}\ge 2\times {\mathbf{nnz}}$.The nonzero elements in the matrix A$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_real_gen_sort (f11za) may be used to order the elements in this way.
- 3: irow(la) – int64int32nag_int array
- 4: icol(la) – int64int32nag_int array
- la, the dimension of the array, must satisfy the constraint la ≥ 2 × nnz${\mathbf{la}}\ge 2\times {\mathbf{nnz}}$.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_real_gen_sort (f11za)):- 1 ≤ irow(i) ≤ n$1\le {\mathbf{irow}}\left(\mathit{i}\right)\le {\mathbf{n}}$ and 1 ≤ icol(i) ≤ n$1\le {\mathbf{icol}}\left(\mathit{i}\right)\le {\mathbf{n}}$, for i = 1,2, … ,nnz$\mathit{i}=1,2,\dots ,{\mathbf{nnz}}$;
- either irow(i − 1) < irow(i)${\mathbf{irow}}\left(\mathit{i}-1\right)<{\mathbf{irow}}\left(\mathit{i}\right)$ or both irow(i − 1) = irow(i)${\mathbf{irow}}\left(\mathit{i}-1\right)={\mathbf{irow}}\left(\mathit{i}\right)$ and icol(i − 1) < icol(i)${\mathbf{icol}}\left(\mathit{i}-1\right)<{\mathbf{icol}}\left(\mathit{i}\right)$, for i = 2,3, … ,nnz$\mathit{i}=2,3,\dots ,{\mathbf{nnz}}$.

- 5: lfill – int64int32nag_int scalar
- If lfill ≥ 0${\mathbf{lfill}}\ge 0$ its value is the maximum level of fill allowed in the decomposition (see Section [Control of Fill-in]). A negative value of lfill indicates that dtol will be used to control the fill instead.
- 6: dtol – double scalar
- If lfill < 0${\mathbf{lfill}}<0$, dtol is used as a drop tolerance to control the fill-in (see Section [Control of Fill-in]); otherwise dtol is not referenced.
- 7: milu – string (length ≥ 1)
- Indicates whether or not the factorization should be modified to preserve row-sums (see Section [Choice of s]).
- 8: ipivp(n) – int64int32nag_int array
- 9: ipivq(n) – int64int32nag_int array

- 1: n – int64int32nag_int scalar
*Default*: The dimension of the arrays ipivp, ipivq. (An error is raised if these dimensions are not equal.)n$n$, the order of the matrix A$A$.- 2: la – int64int32nag_int scalar
*Default*: The dimension of the arrays a, irow, icol. (An error is raised if these dimensions are not equal.)- 3: pstrat – string (length ≥ 1)
- Specifies the pivoting strategy to be adopted.
- pstrat = 'N'${\mathbf{pstrat}}=\text{'N'}$
- No pivoting is carried out.
- pstrat = 'U'${\mathbf{pstrat}}=\text{'U'}$
- Pivoting is carried out according to the user-defined input values of ipivp and ipivq.
- pstrat = 'P'${\mathbf{pstrat}}=\text{'P'}$
- Partial pivoting by columns for stability is carried out.
- pstrat = 'C'${\mathbf{pstrat}}=\text{'C'}$
- Complete pivoting by rows for sparsity, and by columns for stability, is carried out.

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

- iwork liwork

- 1: a(la) – double array
- 2: irow(la) – int64int32nag_int array
- 3: icol(la) – int64int32nag_int array
- The row and column indices of the nonzero elements returned in a.
- 4: ipivp(n) – int64int32nag_int array
- 5: ipivq(n) – int64int32nag_int array
- 6: istr(n + 1${\mathbf{n}}+1$) – int64int32nag_int array
- istr(i)${\mathbf{istr}}\left(\mathit{i}\right)$, for i = 1,2, … ,n$\mathit{i}=1,2,\dots ,{\mathbf{n}}$, is the starting address in the arrays a, irow and icol of row i$i$ of the matrix C$C$. istr(n + 1)${\mathbf{istr}}\left({\mathbf{n}}+1\right)$ is the address of the last nonzero element in C$C$ plus one.
- 7: idiag(n) – int64int32nag_int array
- 8: nnzc – int64int32nag_int scalar
- The number of nonzero elements in the matrix C$C$.
- 9: npivm – int64int32nag_int scalar
- If npivm > 0${\mathbf{npivm}}>0$ it gives the number of pivots which were modified during the factorization to ensure that M$M$ exists.If npivm = − 1${\mathbf{npivm}}=-1$ no pivot modifications were required, but a local restart occurred (see Section [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_real_gen_precon_ilu (f11da) again with an increased value of lfill, a reduced value of dtol, or set pstrat = 'C'${\mathbf{pstrat}}=\text{'C'}$. See also Section [Direct Solution of Sparse Linear Systems].
- 10: ifail – int64int32nag_int scalar
- ifail = 0${\mathrm{ifail}}={\mathbf{0}}$ unless the function detects an error (see [Error Indicators and Warnings]).

Errors or warnings detected by the function:

On entry, n < 1${\mathbf{n}}<1$, or nnz < 1${\mathbf{nnz}}<1$, or nnz > n ^{2}${\mathbf{nnz}}>{{\mathbf{n}}}^{2}$,or la < 2 × nnz${\mathbf{la}}<2\times {\mathbf{nnz}}$, or lfill < 0${\mathbf{lfill}}<0$ and dtol < 0.0${\mathbf{dtol}}<0.0$, or pstrat ≠ 'N'${\mathbf{pstrat}}\ne \text{'N'}$, 'U'$\text{'U'}$, 'P'$\text{'P'}$ or 'C'$\text{'C'}$, or milu ≠ 'M'${\mathbf{milu}}\ne \text{'M'}$ or 'N'$\text{'N'}$, or liwork < 7 × n + 2$\mathit{liwork}<7\times {\mathbf{n}}+2$.

- On entry, the arrays irow and icol fail to satisfy the following constraints:
- 1 ≤ irow(i) ≤ n$1\le {\mathbf{irow}}\left(\mathit{i}\right)\le {\mathbf{n}}$ and 1 ≤ icol(i) ≤ n$1\le {\mathbf{icol}}\left(\mathit{i}\right)\le {\mathbf{n}}$, for i = 1,2, … ,nnz$\mathit{i}=1,2,\dots ,{\mathbf{nnz}}$;
- irow(i − 1) < irow(i)${\mathbf{irow}}\left(\mathit{i}-1\right)<{\mathbf{irow}}\left(\mathit{i}\right)$ or irow(i − 1) = irow(i)${\mathbf{irow}}\left(\mathit{i}-1\right)={\mathbf{irow}}\left(\mathit{i}\right)$ and icol(i − 1) < icol(i)${\mathbf{icol}}\left(\mathit{i}-1\right)<{\mathbf{icol}}\left(\mathit{i}\right)$, for i = 2,3, … ,nnz$\mathit{i}=2,3,\dots ,{\mathbf{nnz}}$.

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

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

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$A$. The factorization can generally be made more accurate by increasing lfill, or by reducing dtol with lfill < 0${\mathbf{lfill}}<0$.

If nag_sparse_real_gen_precon_ilu (f11da) is used in combination with nag_sparse_real_gen_basic_solver (f11be) or nag_sparse_real_gen_solve_ilu (f11dc), the more accurate the factorization the fewer iterations will be required. However, the cost of the decomposition will also generally increase.

The time taken for a call to nag_sparse_real_gen_precon_ilu (f11da) is roughly proportional to (nnzc)^{2} / n${\left({\mathbf{nnzc}}\right)}^{2}/{\mathbf{n}}$.

If lfill ≥ 0${\mathbf{lfill}}\ge 0$ the amount of fill-in occurring in the incomplete factorization is controlled by limiting the maximum **level** of fill-in to lfill. The original nonzero elements of A$A$ are defined to be of level 0$0$. The fill level of a new nonzero location occurring during the factorization is defined as:

where k_{e}${k}_{\mathrm{e}}$ is the level of fill of the element being eliminated, and k_{c}${k}_{\mathrm{c}}$ is the level of fill of the element causing the fill-in.

k = max (k _{e},k_{c}) + 1,
$$k=\mathrm{max}\phantom{\rule{0.125em}{0ex}}({k}_{\mathrm{e}},{k}_{\mathrm{c}})+1\text{,}$$ |

If lfill < 0${\mathbf{lfill}}<0$ the fill-in is controlled by means of the **drop tolerance**
dtol. A potential fill-in element a_{ij}${a}_{ij}$ occurring in row i$i$ and column j$j$ will not be included if:

where α$\alpha $ is the maximum absolute value element in the matrix A$A$.

$$\left|{a}_{ij}\right|<{\mathbf{dtol}}\times \alpha \text{,}$$ |

For either method of control, any elements which are not included are discarded unless milu = 'M'${\mathbf{milu}}=\text{'M'}$, in which case their contributions are subtracted from the pivot element in the relevant elimination row, to preserve the row-sums of the original matrix.

Should the factorization process break down a local restart process is implemented as described in Section [Algorithmic Details]. This will affect the amount of fill present in the final factorization.

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 fill-in. Otherwise the rows are treated in the order given, or some user-defined order.

The chosen row is copied from the original matrix A$A$ and modified according to those previous elimination stages which affect it. During this process any fill-in elements are either dropped or kept according to the values of lfill or dtol. In the case of a modified factorization (milu = 'M'${\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 user-defined 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 fill. Note that in this case the final factorization will include more fill than originally specified by the user-supplied value of lfill or dtol. The local restart usually results in a suitable nonzero pivot arising. The original criteria for dropping fill-in 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_real_gen_precon_ilu (f11da) returns an integer parameter npivm which gives the number of these arbitrary unit pivots introduced. If no pivots were modified but local restarts occurred npivm = − 1${\mathbf{npivm}}=-1$ is returned.

There is unfortunately no choice of the various algorithmic parameters which is optimal for all types of matrix, and some experimentation will generally be required for each new type of matrix encountered.

If the matrix A$A$ is not known to have any particular special properties the following strategy is recommended. Start with lfill = 0${\mathbf{lfill}}=0$ and pstrat = 'C'${\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$M$ existed, the preconditioner is not likely to be satisfactory. In this case increase lfill until npivm falls to a value close to zero.

If A$A$ has non-positive off-diagonal elements, is nonsingular, and has only non-negative elements in its inverse, it is called an ‘M-matrix’. It can be shown that no pivot modifications are required in the incomplete LU$LU$ factorization of an M-matrix (see Meijerink and Van der Vorst (1977)). In this case a good preconditioner can generally be expected by setting lfill = 0${\mathbf{lfill}}=0$, pstrat = 'N'${\mathbf{pstrat}}=\text{'N'}$ and milu = 'M'${\mathbf{milu}}=\text{'M'}$.

Some illustrations of the application of nag_sparse_real_gen_precon_ilu (f11da) to linear systems arising from the discretization of two-dimensional elliptic partial differential equations, and to random-valued randomly structured linear systems, can be found in Salvini and Shaw (1996).

Although it is not their primary purpose nag_sparse_real_gen_precon_ilu (f11da) and nag_sparse_real_gen_precon_ilu_solve (f11db) may be used together to obtain a **direct** solution to a nonsingular sparse linear system. To achieve this the call to nag_sparse_real_gen_precon_ilu_solve (f11db) should be preceded by a **complete**
LU$LU$ factorization

a complete factorization is obtained from a call to nag_sparse_real_gen_precon_ilu (f11da) with lfill < 0${\mathbf{lfill}}<0$ and dtol = 0.0${\mathbf{dtol}}=0.0$, provided npivm ≤ 0${\mathbf{npivm}}\le 0$ on exit. A positive value of npivm indicates that A$A$ is singular, or ill-conditioned. 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.

A = PLDUQ = M.
$$A=PLDUQ=M\text{.}$$ |

The use of nag_sparse_real_gen_precon_ilu (f11da) and nag_sparse_real_gen_precon_ilu_solve (f11db) as a direct method is illustrated in Section [Example] in (f11db).

Open in the MATLAB editor: nag_sparse_real_gen_precon_ilu_example

function nag_sparse_real_gen_precon_ilu_examplenz = int64(11); a = zeros(2*nz, 1); a(1:nz) = [1; 1; -1; 2; 2; 3; -2; 1; -2; 1; 1]; irow = zeros(2*nz, 1, 'int64'); irow(1:nz) = [int64(1); 1; 2; 2; 2; 3; 3; 4; 4; 4; 4]; icol = zeros(2*nz, 1, 'int64'); 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]; [aOut, irowOut, icolOut, ipivpOut, ipivqOut, istr, idiag, nnzc, npivm, ifail] = ... nag_sparse_real_gen_precon_ilu(nz, a, irow, icol, lfill, dtol, milu, ipivp, ipivq)

aOut = 1.0000 1.0000 -1.0000 2.0000 2.0000 3.0000 -2.0000 1.0000 -2.0000 1.0000 1.0000 1.0000 1.0000 0.3333 -0.6667 -0.3333 0.5000 0.6667 -2.0000 0.3333 1.5000 -3.0000 irowOut = 1 1 2 2 2 3 3 4 4 4 4 1 1 2 2 3 3 3 4 4 4 4 icolOut = 2 3 1 3 4 1 4 1 2 3 4 1 3 2 4 2 3 4 1 2 3 4 ipivpOut = 1 3 2 4 ipivqOut = 2 1 3 4 istr = 12 14 16 19 23 idiag = 12 14 17 22 nnzc = 11 npivm = 0 ifail = 0

Open in the MATLAB editor: f11da_example

function f11da_examplenz = int64(11); a = zeros(2*nz, 1); a(1:nz) = [1; 1; -1; 2; 2; 3; -2; 1; -2; 1; 1]; irow = zeros(2*nz, 1, 'int64'); irow(1:nz) = [int64(1); 1; 2; 2; 2; 3; 3; 4; 4; 4; 4]; icol = zeros(2*nz, 1, 'int64'); 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]; [aOut, irowOut, icolOut, ipivpOut, ipivqOut, istr, idiag, nnzc, npivm, ifail] = ... f11da(nz, a, irow, icol, lfill, dtol, milu, ipivp, ipivq)

aOut = 1.0000 1.0000 -1.0000 2.0000 2.0000 3.0000 -2.0000 1.0000 -2.0000 1.0000 1.0000 1.0000 1.0000 0.3333 -0.6667 -0.3333 0.5000 0.6667 -2.0000 0.3333 1.5000 -3.0000 irowOut = 1 1 2 2 2 3 3 4 4 4 4 1 1 2 2 3 3 3 4 4 4 4 icolOut = 2 3 1 3 4 1 4 1 2 3 4 1 3 2 4 2 3 4 1 2 3 4 ipivpOut = 1 3 2 4 ipivqOut = 2 1 3 4 istr = 12 14 16 19 23 idiag = 12 14 17 22 nnzc = 11 npivm = 0 ifail = 0

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2013