f11jnc computes an incomplete Cholesky factorization of a complex sparse Hermitian matrix, represented in symmetric coordinate storage format. This factorization may be used as a preconditioner in combination with f11jqc.
The function may be called by the names: f11jnc, nag_sparse_complex_herm_precon_ichol or nag_sparse_herm_chol_fac.
3Description
f11jnc computes an incomplete Cholesky factorization (see Meijerink and Van der Vorst (1977)) of a complex sparse Hermitian $n\times n$ matrix $A$. 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 the complex Hermitian iterative solver f11jqc.
The decomposition is written in the form
$$A=M+R$$
where
$$M=PLD{L}^{\mathrm{H}}{P}^{\mathrm{T}}$$
and $P$ is a permutation matrix, $L$ is lower triangular complex with unit diagonal elements, $D$ is real diagonal and $R$ 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 9.
The sparse matrix $A$ 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 $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 SCS representation of the lower triangular matrix
$$C=L+{D}^{-1}-I\text{.}$$
4References
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
5Arguments
1: $\mathbf{n}$ – IntegerInput
On entry: $n$, the order of the matrix $A$.
Constraint:
${\mathbf{n}}\ge 1$.
2: $\mathbf{nnz}$ – IntegerInput
On entry: the number of nonzero elements in the lower triangular part of the matrix $A$.
On entry: the nonzero elements in the lower triangular part of 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 f11zpc may be used to order the elements in this way.
On exit: the first nnz elements of a contain the nonzero elements of $A$ and the next nnzc elements contain the elements of the lower triangular matrix $C$. Matrix elements are ordered by increasing row index, and by increasing column index within each row.
4: $\mathbf{la}$ – IntegerInput
On entry: the dimension of the arrays a, irow and icol. These arrays must be of sufficient size to store both $A$ (nnz elements) and $C$ (nnzc elements).
On entry: 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 f11zpc):
$1\le {\mathbf{irow}}\left[\mathit{i}\right]\le {\mathbf{n}}$ and $1\le {\mathbf{icol}}\left[\mathit{i}\right]\le {\mathbf{irow}}\left[\mathit{i}\right]$, for $\mathit{i}=0,1,\dots ,{\mathbf{nnz}}-1$;
${\mathbf{irow}}\left[\mathit{i}-1\right]<{\mathbf{irow}}\left[\mathit{i}\right]$ or ${\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}=1,2,\dots ,{\mathbf{nnz}}-1$.
On exit: the row and column indices of the nonzero elements returned in a.
7: $\mathbf{lfill}$ – IntegerInput
On entry: if ${\mathbf{lfill}}\ge 0$ its value is the maximum level of fill allowed in the decomposition (see Section 9.2). A negative value of lfill indicates that dtol will be used to control the fill instead.
8: $\mathbf{dtol}$ – doubleInput
On entry: if ${\mathbf{lfill}}<0$, dtol is used as a drop tolerance to control the fill-in (see Section 9.2); otherwise dtol is not referenced.
Constraint:
if ${\mathbf{lfill}}<0$, ${\mathbf{dtol}}\ge 0.0$.
9: $\mathbf{mic}$ – Nag_SparseSym_FactInput
On entry: indicates whether or not the factorization should be modified to preserve row sums (see Section 9.3).
Constraint:
${\mathbf{mic}}=\mathrm{Nag\_SparseSym\_ModFact}$ or $\mathrm{Nag\_SparseSym\_UnModFact}$.
10: $\mathbf{dscale}$ – doubleInput
On entry: the diagonal scaling parameter. All diagonal elements are multiplied by the factor ($1.0+{\mathbf{dscale}}$) at the start of the factorization. This can be used to ensure that the preconditioner is positive definite. See also Section 9.3.
11: $\mathbf{pstrat}$ – Nag_SparseSym_PivInput
On entry: specifies the pivoting strategy to be adopted.
On entry: if ${\mathbf{pstrat}}=\mathrm{Nag\_SparseSym\_UserPiv}$, ${\mathbf{ipiv}}\left[i-1\right]$ must specify the row index of the diagonal element to be used as a pivot at elimination stage $i$. Otherwise ipiv need not be initialized.
Constraint:
if ${\mathbf{pstrat}}=\mathrm{Nag\_SparseSym\_UserPiv}$, ipiv must contain a valid permutation of the integers on $[1,{\mathbf{n}}]$.
On exit: the pivot indices. If ${\mathbf{ipiv}}\left[i-1\right]=j$, the diagonal element in row $j$ was used as the pivot at elimination stage $i$.
On exit: ${\mathbf{istr}}\left[\mathit{i}-1\right]-1$, 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}}\right]-1$ is the address of the last nonzero element in $C$ plus one.
14: $\mathbf{nnzc}$ – Integer *Output
On exit: the number of nonzero elements in the lower triangular matrix $C$.
15: $\mathbf{npivm}$ – Integer *Output
On exit: the number of pivots which were modified during the factorization to ensure that $M$ 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 f11jnc again with an increased value of either lfill or dscale. See also Sections 9.3 and 9.4.
16: $\mathbf{fail}$ – NagError *Input/Output
The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).
6Error Indicators and Warnings
A nonzero element has been supplied which does not lie in the lower triangular part of $A$, is out of order, or has duplicate row and column indices. Consider calling f11zpc to reorder and sum or remove duplicates.
NE_ALLOC_FAIL
Dynamic memory allocation failed.
See Section 3.1.2 in the Introduction to the NAG Library CL Interface for further information.
NE_BAD_PARAM
On entry, argument $\u27e8\mathit{\text{value}}\u27e9$ had an illegal value.
NE_INT
On entry, ${\mathbf{n}}=\u27e8\mathit{\text{value}}\u27e9$.
Constraint: ${\mathbf{n}}\ge 1$.
On entry, ${\mathbf{nnz}}=\u27e8\mathit{\text{value}}\u27e9$.
Constraint: ${\mathbf{nnz}}\ge 1$.
NE_INT_2
On entry, ${\mathbf{la}}=\u27e8\mathit{\text{value}}\u27e9$ and ${\mathbf{nnz}}=\u27e8\mathit{\text{value}}\u27e9$.
Constraint: ${\mathbf{la}}\ge 2\times {\mathbf{nnz}}$.
On entry, ${\mathbf{nnz}}=\u27e8\mathit{\text{value}}\u27e9$ and ${\mathbf{n}}=\u27e8\mathit{\text{value}}\u27e9$.
Constraint: ${\mathbf{nnz}}\le {\mathbf{n}}\times ({\mathbf{n}}+1)/2$
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
See Section 7.5 in the Introduction to the NAG Library CL Interface for further information.
A serious error has occurred in an internal call. Check all function calls and array sizes. Seek expert help.
NE_INVALID_ROWCOL_PIVOT
On entry, a user-supplied value of ipiv is repeated.
On entry, a user-supplied value of ipiv lies outside the range $[1,{\mathbf{n}}]$.
NE_INVALID_SCS
On entry, $\mathit{I}=\u27e8\mathit{\text{value}}\u27e9$, ${\mathbf{icol}}\left[\mathit{I}-1\right]=\u27e8\mathit{\text{value}}\u27e9$ and ${\mathbf{irow}}\left[\mathit{I}-1\right]=\u27e8\mathit{\text{value}}\u27e9$.
Constraint: ${\mathbf{icol}}\left[\mathit{I}-1\right]\ge 1$ and ${\mathbf{icol}}\left[\mathit{I}-1\right]\le {\mathbf{irow}}\left[\mathit{I}-1\right]$.
On entry, $\mathit{I}=\u27e8\mathit{\text{value}}\u27e9$, ${\mathbf{irow}}\left[\mathit{I}-1\right]=\u27e8\mathit{\text{value}}\u27e9$ and ${\mathbf{n}}=\u27e8\mathit{\text{value}}\u27e9$.
Constraint: ${\mathbf{irow}}\left[\mathit{I}-1\right]\ge 1$ and ${\mathbf{irow}}\left[\mathit{I}-1\right]\le {\mathbf{n}}$.
NE_NO_LICENCE
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library CL Interface for further information.
NE_NOT_STRICTLY_INCREASING
On entry, ${\mathbf{a}}\left[i-1\right]$ is out of order: $i=\u27e8\mathit{\text{value}}\u27e9$.
On entry, the location (${\mathbf{irow}}\left[\mathit{I}-1\right],{\mathbf{icol}}\left[\mathit{I}-1\right]$) is a duplicate: $\mathit{I}=\u27e8\mathit{\text{value}}\u27e9$.
NE_REAL
On entry, ${\mathbf{dtol}}=\u27e8\mathit{\text{value}}\u27e9$.
Constraint: ${\mathbf{dtol}}\ge 0.0$
NE_TOO_SMALL
The number of nonzero entries in the decomposition is too large. The decomposition has been terminated before completion. Either increase la, or reduce the fill by setting ${\mathbf{pstrat}}=\mathrm{Nag\_SparseSym\_MarkPiv}$, reducing lfill, or increasing dtol.
7Accuracy
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 $A$. The factorization can generally be made more accurate by increasing lfill, or by reducing dtol with ${\mathbf{lfill}}<0$.
If f11jnc is used in combination with f11jqc, the more accurate the factorization the fewer iterations will be required. However, the cost of the decomposition will also generally increase.
8Parallelism and Performance
f11jnc makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this function. Please also consult the Users' Note for your implementation for any additional implementation-specific information.
9Further Comments
9.1Timing
The time taken for a call to f11jnc is roughly proportional to ${{\mathbf{nnzc}}}^{2}/{\mathbf{n}}$.
9.2Control of Fill-in
If ${\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$ 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 fill-in.
If ${\mathbf{lfill}}<0$, the fill-in is controlled by means of the ‘drop tolerance’ dtol. A potential fill-in element ${a}_{ij}$ occurring in row $i$ and column $j$ will not be included if
For either method of control, any elements which are not included are discarded if ${\mathbf{mic}}=\mathrm{Nag\_SparseSym\_UnModFact}$, or subtracted from the diagonal element in the elimination row if ${\mathbf{mic}}=\mathrm{Nag\_SparseSym\_ModFact}$.
9.3Choice of Arguments
There is unfortunately no choice of the various algorithmic arguments which is optimal for all types of complex Hermitian matrix, and some experimentation will generally be required for each new type of matrix encountered.
If the matrix $A$ is not known to have any particular special properties, the following strategy is recommended. Start with ${\mathbf{lfill}}=0$, ${\mathbf{mic}}=\mathrm{Nag\_SparseSym\_UnModFact}$ and ${\mathbf{dscale}}=0.0$. 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$ was positive definite, the preconditioner is not likely to be satisfactory. In this case increase either lfill or dscale until npivm falls to a value close to zero. Once suitable values of lfill and dscale have been found try setting ${\mathbf{mic}}=\mathrm{Nag\_SparseSym\_ModFact}$ to see if any improvement can be obtained by using modified incomplete Cholesky.
f11jnc is primarily designed for positive definite matrices, but may work for some mildly indefinite problems. If npivm cannot be satisfactorily reduced by increasing lfill or dscale then $A$ is probably too indefinite for this function.
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 ${\mathbf{mic}}=\mathrm{Nag\_SparseSym\_ModFact}$.
9.4Direct Solution of positive definite Systems
Although it is not their primary purpose, f11jnc and f11jpc may be used together to obtain a direct solution to a complex Hermitian positive definite linear system. To achieve this the call to f11jpc should be preceded by a complete Cholesky factorization
A complete factorization is obtained from a call to f11jnc with ${\mathbf{lfill}}<0$ and ${\mathbf{dtol}}=0.0$, provided ${\mathbf{npivm}}=0$ 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 f11jnc and f11jpc as a direct method is illustrated in f11jpc.
10Example
This example reads in a complex sparse Hermitian matrix $A$ and calls f11jnc to compute an incomplete Cholesky factorization. It then outputs the nonzero elements of both $A$ and $C=L+{D}^{-1}-I$.
The call to f11jnc has ${\mathbf{lfill}}=0$, ${\mathbf{mic}}=\mathrm{Nag\_SparseSym\_UnModFact}$, ${\mathbf{dscale}}=0.0$ and ${\mathbf{pstrat}}=\mathrm{Nag\_SparseSym\_MarkPiv}$, giving an unmodified zero-fill factorization of an unperturbed matrix, with Markowitz diagonal pivoting.