NAG Library Routine Document
F11JAF computes an incomplete Cholesky factorization of a real sparse symmetric matrix, represented in symmetric coordinate storage format. This factorization may be used as a preconditioner in combination with F11GEF
|SUBROUTINE F11JAF (
||N, NNZ, A, LA, IROW, ICOL, LFILL, DTOL, MIC, DSCALE, PSTRAT, IPIV, ISTR, NNZC, NPIVM, IWORK, LIWORK, IFAIL)
||N, NNZ, LA, IROW(LA), ICOL(LA), LFILL, IPIV(N), ISTR(N+1), NNZC, NPIVM, IWORK(LIWORK), LIWORK, IFAIL
||A(LA), DTOL, DSCALE
F11JAF computes an incomplete Cholesky factorization (see Meijerink and Van der Vorst (1977)
) of a real sparse symmetric
. It is designed specifically for positive definite matrices, but may also work for some mildly indefinite cases. The factorization is intended primarily for use as a preconditioner with one of the symmetric iterative solvers F11GEF
The decomposition is written in the form
is a permutation matrix,
is lower triangular with unit diagonal elements,
is diagonal 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 factorization may be modified in order to preserve row sums, and the diagonal elements may be perturbed to ensure that the preconditioner is positive definite. Diagonal pivoting may optionally be employed, either with a user-defined ordering, or using the Markowitz strategy (see Markowitz (1957)
), which aims to minimize fill-in. For further details see Section 8
The sparse matrix
is represented in symmetric coordinate storage (SCS) format (see Section 2.1.2
in the F11 Chapter Introduction). The array A
stores all the nonzero elements of the lower triangular part of
, 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 SCS representation of the lower triangular matrix
Chan T F (1991) Fourier analysis of relaxed incomplete factorization preconditioners SIAM J. Sci. Statist. Comput. 12(2) 668–680
Markowitz H M (1957) The elimination form of the inverse and its application to linear programming Management Sci. 3 255–269
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
Salvini S A and Shaw G J (1995) An evaluation of new NAG Library solvers for large sparse symmetric linear systems NAG Technical Report TR1/95
Van der Vorst H A (1990) The convergence behaviour of preconditioned CG and CG-S in the presence of rounding errors Lecture Notes in Mathematics (eds O Axelsson and L Y Kolotilina) 1457 Springer–Verlag
- 1: N – INTEGERInput
On entry: , the order of the matrix .
- 2: NNZ – INTEGERInput
On entry: the number of nonzero elements in the lower triangular part of the matrix .
- 3: A(LA) – REAL (KIND=nag_wp) arrayInput/Output
: the nonzero elements in the lower triangular part of 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 F11ZBF
may be used to order the elements in this way.
: the first NNZ
elements of A
contain the nonzero elements of
and the next NNZC
elements contain the elements of the lower triangular 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 F11JAF 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 F11ZBF
- and , for ;
- or 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: MIC – CHARACTER(1)Input
: indicates whether or not the factorization should be modified to preserve row sums (see Section 8.3
- The factorization is modified.
- The factorization is not modified.
- 10: DSCALE – REAL (KIND=nag_wp)Input
: the diagonal scaling parameter. All diagonal elements are multiplied by the factor (
) at the start of the factorization. This can be used to ensure that the preconditioner is positive definite. See Section 8.3
- 11: PSTRAT – CHARACTER(1)Input
: specifies the pivoting strategy to be adopted.
- No pivoting is carried out.
- Diagonal pivoting aimed at minimizing fill-in is carried out, using the Markowitz strategy.
- Diagonal pivoting is carried out according to the user-defined input value of IPIV.
, or .
- 12: IPIV(N) – INTEGER arrayInput/Output
must specify the row index of the diagonal element used as a pivot at elimination stage
. Otherwise IPIV
need not be initialized.
must contain a valid permutation of the integers on [1,N
On exit: the pivot indices. If then the diagonal element in row 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: NNZC – INTEGEROutput
On exit: the number of nonzero elements in the lower triangular matrix .
- 15: NPIVM – INTEGEROutput
: the number of pivots which were modified during the factorization to ensure that
was positive definite. 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 F11JAF again with an increased value of either LFILL
. See also Section 8.4
- 16: IWORK(LIWORK) – INTEGER arrayWorkspace
- 17: LIWORK – INTEGERInput
: the dimension of the array IWORK
as declared in the (sub)program from which F11JAF is called.
the minimum permissible value of LIWORK
depends on LFILL
- if , ;
- if , .
- 18: 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|| or ,|
|or||, or ,|
|or||, and ,|
|or||, and .|
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 in the lower triangular part of
, is out of order, or has duplicate row and column indices. Call F11ZBF
to reorder and sum or remove duplicates.
, but IPIV
does not represent a valid permutation of the integers in
. An input value of IPIV
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 setting
, 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 diagonal 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 F11JAF is used in combination with F11GEF
, 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 F11JAF 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
For either method of control, any elements which are not included are discarded if , or subtracted from the diagonal element in the elimination row if .
There is unfortunately no choice of the various algorithmic parameters which is optimal for all types of symmetric matrix, and some experimentation will generally be required for each new type of matrix encountered.
If the matrix
is not known to have any particular special properties the following strategy is recommended. 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
was positive definite, the preconditioner is not likely to be satisfactory. In this case increase either LFILL
falls to a value close to zero. Once suitable values of LFILL
have been found try setting
to see if any improvement can be obtained by using modified
F11JAF is primarily designed for positive definite matrices, but may work for some mildly indefinite problems. If NPIVM
cannot be satisfactorily reduced by increasing LFILL
is probably too indefinite for this routine.
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 Cholesky factorization of an M-matrix (see Meijerink and Van der Vorst (1977)
). In this case a good preconditioner can generally be expected by setting
For certain mesh-based problems involving M-matrices it can be shown in theory that setting
, and choosing DSCALE
appropriately can reduce the order of magnitude of the condition number of the preconditioned matrix as a function of the mesh steplength (see Chan (1991)
). In practise this property often holds even with
, although an improvement in condition can result from increasing DSCALE
slightly (see Van der Vorst (1990)
Some illustrations of the application of F11JAF to linear systems arising from the discretization of two-dimensional elliptic partial differential equations, and to random-valued randomly structured symmetric positive definite linear systems, can be found in Salvini and Shaw (1995)
Although it is not their primary purpose, F11JAF and F11JBF
may be used together to obtain a direct
solution to a symmetric positive definite linear system. To achieve this the call to F11JBF
should be preceded by a complete
A complete factorization is obtained from a call to F11JAF with
on exit. A nonzero value of NPIVM
indicates that A
is not positive definite, or is ill-conditioned. A factorization with nonzero 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 F11JAF and F11JBF
as a direct method is illustrated in Section 9
This example reads in a symmetric sparse matrix and calls F11JAF to compute an incomplete Cholesky factorization. It then outputs the nonzero elements of both and .
The call to F11JAF has , , and , giving an unmodified zero-fill factorization of an unperturbed matrix, with Markowitz diagonal pivoting.
9.1 Program Text
Program Text (f11jafe.f90)
9.2 Program Data
Program Data (f11jafe.d)
9.3 Program Results
Program Results (f11jafe.r)