NAG Library Routine Document
F11DNF computes an incomplete
factorization of a complex sparse non-Hermitian matrix, represented in coordinate storage format. This factorization may be used as a preconditioner in combination with F11BSF
|SUBROUTINE F11DNF (
||N, NNZ, A, LA, IROW, ICOL, LFILL, DTOL, PSTRAT, MILU, IPIVP, IPIVQ, ISTR, IDIAG, NNZC, NPIVM, IWORK, LIWORK, IFAIL)
||N, NNZ, LA, IROW(LA), ICOL(LA), LFILL, IPIVP(N), IPIVQ(N), ISTR(N+1), IDIAG(N), NNZC, NPIVM, IWORK(LIWORK), LIWORK, IFAIL
F11DNF computes an incomplete
factorization (see Meijerink and Van der Vorst (1977)
and Meijerink and Van der Vorst (1981)
) of a complex sparse non-Hermitian
. The factorization is intended primarily for use as a preconditioner with one of the iterative solvers F11BSF
The decomposition is written in the form
is lower triangular with unit diagonal elements,
is upper triangular with unit diagonals,
are permutation matrices, and
is a remainder matrix.
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
is represented in coordinate storage (CS) format (see Section 2.1.1
in the F11 Chapter Introduction). The array A
stores all the nonzero elements of the matrix
, while arrays IROW
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
is returned in terms of the CS representation of the matrix
Further algorithmic details are given in Section 8.3
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
- 1: N – INTEGERInput
On entry: , the order of the matrix .
- 2: NNZ – INTEGERInput
On entry: the number of nonzero elements in the matrix .
- 3: A(LA) – COMPLEX (KIND=nag_wp) arrayInput/Output
: the nonzero elements in the matrix
, 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 routine F11ZNF
may be used to order the elements in this way.
: the first NNZ
entries of A
contain the nonzero elements of
and the next NNZC
entries contain the elements of the matrix
. Matrix elements are ordered by increasing row index, and by increasing column index within each row.
- 4: LA – INTEGERInput
: the dimension of the arrays A
as declared in the (sub)program from which F11DNF is called. These arrays must be of sufficient size to store both
- 5: IROW(LA) – INTEGER arrayInput/Output
- 6: ICOL(LA) – INTEGER arrayInput/Output
: the row and column indices of the nonzero elements supplied in A
must satisfy these constraints (which may be imposed by a call to F11ZNF
- and , for ;
- either or both and , for .
: the row and column indices of the nonzero elements returned in A
- 7: LFILL – INTEGERInput
its value is the maximum level of fill allowed in the decomposition (see Section 8.2
). A negative value of LFILL
indicates that DTOL
will be used to control the fill instead.
- 8: DTOL – REAL (KIND=nag_wp)Input
is used as a drop tolerance to control the fill-in (see Section 8.2
); otherwise DTOL
is not referenced.
if , .
- 9: PSTRAT – CHARACTER(1)Input
: specifies the pivoting strategy to be adopted.
- No pivoting is carried out.
- Pivoting is carried out according to the user-defined input values of IPIVP and IPIVQ.
- Partial pivoting by columns for stability is carried out.
- Complete pivoting by rows for sparsity, and by columns for stability, is carried out.
, , or .
- 10: MILU – CHARACTER(1)Input
: indicates whether or not the factorization should be modified to preserve row-sums (see Section 8.4
- The factorization is modified.
- The factorization is not modified.
- 11: IPIVP(N) – INTEGER arrayInput/Output
- 12: IPIVQ(N) – INTEGER arrayInput/Output
must specify the row and column indices of the element used as a pivot at elimination stage
. Otherwise IPIVP
need not be initialized.
must both hold valid permutations of the integers on [1,N
On exit: the pivot indices. If and then the element in row and column was used as the pivot at elimination stage .
- 13: ISTR() – INTEGER arrayOutput
, is the starting address in the arrays A
of the matrix
is the address of the last nonzero element in
- 14: IDIAG(N) – INTEGER arrayOutput
, holds the index of arrays A
which holds the diagonal element in row
of the matrix
- 15: NNZC – INTEGEROutput
On exit: the number of nonzero elements in the matrix .
- 16: NPIVM – INTEGEROutput
it gives the number of pivots which were modified during the factorization to ensure that
no pivot modifications were required, but a local restart occurred (see Section 8.3
). The quality of the preconditioner will generally depend on the returned value of NPIVM
is large the preconditioner may not be satisfactory. In this case it may be advantageous to call F11DNF again with an increased value of LFILL
, a reduced value of DTOL
, or set
. See also Section 8.5
- 17: IWORK(LIWORK) – INTEGER arrayWorkspace
- 18: LIWORK – INTEGERInput
: the dimension of the array IWORK
as declared in the (sub)program from which F11DNF is called.
- 19: IFAIL – INTEGERInput/Output
must be set to
. If you are unfamiliar with this parameter you should refer to Section 3.3
in the Essential Introduction for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value
is recommended. If the output of error messages is undesirable, then the value
is recommended. Otherwise, if you are not familiar with this parameter, the recommended value is
. When the value is used it is essential to test the value of IFAIL on exit.
unless the routine detects an error or a warning has been flagged (see Section 6
6 Error Indicators and Warnings
If on entry
, explanatory error messages are output on the current error message unit (as defined by X04AAF
Errors or warnings detected by the routine:
|or|| and ,|
|or||, , or ,|
|or|| or ,|
On entry, the arrays IROW
fail to satisfy the following constraints:
- and , for ;
- , or and , for .
Therefore a nonzero element has been supplied which does not lie within the matrix
, is out of order, or has duplicate row and column indices. Call F11ZNF
to reorder and sum or remove duplicates.
, but one or both of IPIVP
does not represent a valid permutation of the integers in [1,N
]. An input value of IPIVP
is either out of range or repeated.
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
A serious error has occurred in an internal call to the specified routine. Check all subroutine 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
. The factorization can generally be made more accurate by increasing LFILL
, or by reducing DTOL
If F11DNF is used in combination with F11BSF
, 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 F11DNF is roughly proportional to .
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
are defined to be of level
. The fill level of a new nonzero location occurring during the factorization is defined as:
is the level of fill of the element being eliminated, and
is the level of fill of the element causing the fill-in.
the fill-in is controlled by means of the drop tolerance
. A potential fill-in element
occurring in row
will not be included if:
is the maximum modulus element in the matrix
For either method of control, any elements which are not included are discarded unless
, 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 8.3
. 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
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
. In the case of a modified factorization (
) 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-in. Note that in this case the final factorization will include more fill than originally specified by the user-supplied value of LFILL
. 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. F11DNF returns an integer parameter NPIVM
which gives the number of these arbitrary unit pivots introduced. If no pivots were modified but local restarts occurred
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. The recommended approach is to start with
. If the value returned for NPIVM
is significantly larger than zero, i.e., a large number of pivot modifications were required to ensure that
existed, the preconditioner is not likely to be satisfactory. In this case increase LFILL
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 row-sums of the original matrix. In these cases try setting .
Although it is not the primary purpose of the routines F11DNF and F11DPF
, they may be used together to obtain a direct
solution to a nonsingular sparse complex non-Hermitian linear system. To achieve this the call to F11DPF
should be preceded by a complete
A complete factorization is obtained from a call to F11DNF with
on exit. A positive value of NPIVM
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.
The use of F11DNF and F11DPF
as a direct method is illustrated in F11DPF
This example reads in a complex sparse non-Hermitian matrix and calls F11DNF to compute an incomplete factorization. It then outputs the nonzero elements of both and .
The call to F11DNF has , and , giving an unmodified zero-fill factorization, with row pivoting for sparsity and column pivoting for stability.
9.1 Program Text
Program Text (f11dnfe.f90)
9.2 Program Data
Program Data (f11dnfe.d)
9.3 Program Results
Program Results (f11dnfe.r)