NAG FL Interface
f11jnf (complex_herm_precon_ichol)
1
Purpose
f11jnf 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
f11jqf.
2
Specification
Fortran Interface
Subroutine f11jnf ( 
n, nnz, a, la, irow, icol, lfill, dtol, mic, dscale, pstrat, ipiv, istr, nnzc, npivm, iwork, liwork, ifail) 
Integer, Intent (In) 
:: 
n, nnz, la, lfill, liwork 
Integer, Intent (Inout) 
:: 
irow(la), icol(la), ipiv(n), ifail 
Integer, Intent (Out) 
:: 
istr(n+1), nnzc, npivm, iwork(liwork) 
Real (Kind=nag_wp), Intent (In) 
:: 
dtol, dscale 
Complex (Kind=nag_wp), Intent (Inout) 
:: 
a(la) 
Character (1), Intent (In) 
:: 
mic, pstrat 

C Header Interface
#include <nag.h>
void 
f11jnf_ (const Integer *n, const Integer *nnz, Complex a[], const Integer *la, Integer irow[], Integer icol[], const Integer *lfill, const double *dtol, const char *mic, const double *dscale, const char *pstrat, Integer ipiv[], Integer istr[], Integer *nnzc, Integer *npivm, Integer iwork[], const Integer *liwork, Integer *ifail, const Charlen length_mic, const Charlen length_pstrat) 

C++ Header Interface
#include <nag.h> extern "C" {
void 
f11jnf_ (const Integer &n, const Integer &nnz, Complex a[], const Integer &la, Integer irow[], Integer icol[], const Integer &lfill, const double &dtol, const char *mic, const double &dscale, const char *pstrat, Integer ipiv[], Integer istr[], Integer &nnzc, Integer &npivm, Integer iwork[], const Integer &liwork, Integer &ifail, const Charlen length_mic, const Charlen length_pstrat) 
}

The routine may be called by the names f11jnf or nagf_sparse_complex_herm_precon_ichol.
3
Description
f11jnf computes an incomplete Cholesky factorization (see
Meijerink and Van der Vorst (1977)) of a complex sparse Hermitian
$n$ by
$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
f11jqf.
The decomposition is written in the form
where
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 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 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 userdefined ordering, or using the Markowitz strategy (see
Markowitz (1957)), which aims to minimize fillin. 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
4
References
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 Mmatrix 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 CGS in the presence of rounding errors Lecture Notes in Mathematics (eds O Axelsson and L Y Kolotilina) 1457 Springer–Verlag
5
Arguments

1:
$\mathbf{n}$ – Integer
Input

On entry: $n$, the order of the matrix $A$.
Constraint:
${\mathbf{n}}\ge 1$.

2:
$\mathbf{nnz}$ – Integer
Input

On entry: the number of nonzero elements in the lower triangular part of the matrix $A$.
Constraint:
$1\le {\mathbf{nnz}}\le {\mathbf{n}}\times \left({\mathbf{n}}+1\right)/2$.

3:
$\mathbf{a}\left({\mathbf{la}}\right)$ – Complex (Kind=nag_wp) array
Input/Output

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 routine
f11zpf 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}$ – Integer
Input

On entry: the dimension of the arrays
a,
irow and
icol as declared in the (sub)program from which
f11jnf is called. These arrays must be of sufficient size to store both
$A$ (
nnz elements) and
$C$ (
nnzc elements).
Constraint:
${\mathbf{la}}\ge 2\times {\mathbf{nnz}}$.

5:
$\mathbf{irow}\left({\mathbf{la}}\right)$ – Integer array
Input/Output

6:
$\mathbf{icol}\left({\mathbf{la}}\right)$ – Integer array
Input/Output

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
f11zpf):
 $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}=1,2,\dots ,{\mathbf{nnz}}$;
 ${\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}=2,3,\dots ,{\mathbf{nnz}}$.
On exit: the row and column indices of the nonzero elements returned in
a.

7:
$\mathbf{lfill}$ – Integer
Input

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}$ – Real (Kind=nag_wp)
Input

On entry: if
${\mathbf{lfill}}<0$,
dtol is used as a drop tolerance to control the fillin (see
Section 9.2); otherwise
dtol is not referenced.
Constraint:
if ${\mathbf{lfill}}<0$, ${\mathbf{dtol}}\ge 0.0$.

9:
$\mathbf{mic}$ – Character(1)
Input

On entry: indicates whether or not the factorization should be modified to preserve row sums (see
Section 9.3).
 ${\mathbf{mic}}=\text{'M'}$
 The factorization is modified.
 ${\mathbf{mic}}=\text{'N'}$
 The factorization is not modified.
Constraint:
${\mathbf{mic}}=\text{'M'}$ or $\text{'N'}$.

10:
$\mathbf{dscale}$ – Real (Kind=nag_wp)
Input

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}$ – Character(1)
Input

On entry: specifies the pivoting strategy to be adopted.
 ${\mathbf{pstrat}}=\text{'N'}$
 No pivoting is carried out.
 ${\mathbf{pstrat}}=\text{'M'}$
 Diagonal pivoting aimed at minimizing fillin is carried out, using the Markowitz strategy (see Markowitz (1957)).
 ${\mathbf{pstrat}}=\text{'U'}$
 Diagonal pivoting is carried out according to the userdefined input array ipiv.
Suggested value:
${\mathbf{pstrat}}=\text{'M'}$.
Constraint:
${\mathbf{pstrat}}=\text{'N'}$, $\text{'M'}$ or $\text{'U'}$.

12:
$\mathbf{ipiv}\left({\mathbf{n}}\right)$ – Integer array
Input/Output

On entry: if
${\mathbf{pstrat}}=\text{'U'}$,
${\mathbf{ipiv}}\left(i\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}}=\text{'U'}$,
ipiv must contain a valid permutation of the integers on
$\left[1,{\mathbf{n}}\right]$.
On exit: the pivot indices. If ${\mathbf{ipiv}}\left(i\right)=j$, the diagonal element in row $j$ was used as the pivot at elimination stage $i$.

13:
$\mathbf{istr}\left({\mathbf{n}}+1\right)$ – Integer array
Output

On exit:
${\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.

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
f11jnf again with an increased value of either
lfill or
dscale. See also
Sections 9.3 and
9.4.

16:
$\mathbf{iwork}\left({\mathbf{liwork}}\right)$ – Integer array
Workspace

17:
$\mathbf{liwork}$ – Integer
Input

On entry: the dimension of the array
iwork as declared in the (sub)program from which
f11jnf is called.
Constraints:
the minimum permissible value of
liwork depends on
lfill as follows:
 if ${\mathbf{lfill}}\ge 0$, ${\mathbf{liwork}}\ge 2\times {\mathbf{la}}3\times {\mathbf{nnz}}+7\times {\mathbf{n}}+1$;
 otherwise ${\mathbf{liwork}}\ge {\mathbf{la}}{\mathbf{nnz}}+7\times {\mathbf{n}}+1$.

18:
$\mathbf{ifail}$ – Integer
Input/Output

On entry:
ifail must be set to
$0$,
$1$ or
$1$ to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $1$ means that an error message is printed while a value of $1$ means that it is not.
If halting is not appropriate, the value
$1$ or
$1$ is recommended. If message printing is undesirable, then the value
$1$ is recommended. Otherwise, the value
$0$ is recommended.
When the value $\mathbf{1}$ or $\mathbf{1}$ is used it is essential to test the value of ifail on exit.
On exit:
${\mathbf{ifail}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see
Section 6).
6
Error Indicators and Warnings
If on entry
${\mathbf{ifail}}=0$ or
$1$, explanatory error messages are output on the current error message unit (as defined by
x04aaf).
Errors or warnings detected by the routine:
 ${\mathbf{ifail}}=1$

On entry, ${\mathbf{dtol}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{dtol}}\ge 0.0$
On entry, ${\mathbf{la}}=\u2329\mathit{\text{value}}\u232a$ and ${\mathbf{nnz}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{la}}\ge 2\times {\mathbf{nnz}}$.
On entry,
liwork is too small:
${\mathbf{liwork}}=\u2329\mathit{\text{value}}\u232a$. Minimum required value of
${\mathbf{liwork}}=\u2329\mathit{\text{value}}\u232a$.
On entry, ${\mathbf{mic}}\ne \text{'M'}$ or $\text{'N'}$: ${\mathbf{mic}}=\u2329\mathit{\text{value}}\u232a$.
On entry, ${\mathbf{n}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{n}}\ge 1$.
On entry, ${\mathbf{nnz}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{nnz}}\ge 1$.
On entry, ${\mathbf{nnz}}=\u2329\mathit{\text{value}}\u232a$ and ${\mathbf{n}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{nnz}}\le {\mathbf{n}}\times \left({\mathbf{n}}+1\right)/2$
On entry, ${\mathbf{pstrat}}\ne \text{'N'}$, $\text{'U'}$ or $\text{'M'}$: ${\mathbf{pstrat}}=\u2329\mathit{\text{value}}\u232a$.
 ${\mathbf{ifail}}=2$

On entry, ${\mathbf{a}}\left(i\right)$ is out of order: $i=\u2329\mathit{\text{value}}\u232a$.
On entry, $\mathit{I}=\u2329\mathit{\text{value}}\u232a$, ${\mathbf{icol}}\left(\mathit{I}\right)=\u2329\mathit{\text{value}}\u232a$ and ${\mathbf{irow}}\left(\mathit{I}\right)=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{icol}}\left(\mathit{I}\right)\ge 1$ and ${\mathbf{icol}}\left(\mathit{I}\right)\le {\mathbf{irow}}\left(\mathit{I}\right)$.
On entry, $\mathit{I}=\u2329\mathit{\text{value}}\u232a$, ${\mathbf{irow}}\left(\mathit{I}\right)=\u2329\mathit{\text{value}}\u232a$ and ${\mathbf{n}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{irow}}\left(\mathit{I}\right)\ge 1$ and ${\mathbf{irow}}\left(\mathit{I}\right)\le {\mathbf{n}}$.
On entry, the location (${\mathbf{irow}}\left(\mathit{I}\right),{\mathbf{icol}}\left(\mathit{I}\right)$) is a duplicate: $\mathit{I}=\u2329\mathit{\text{value}}\u232a$.
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
f11zpf to reorder and sum or remove duplicates.
 ${\mathbf{ifail}}=3$

On entry, a usersupplied value of
ipiv is repeated.
On entry, a usersupplied value of
ipiv lies outside the range
$\left[1,{\mathbf{n}}\right]$.
 ${\mathbf{ifail}}=4$

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}}=\text{'M'}$, reducing
lfill, or increasing
dtol.
 ${\mathbf{ifail}}=5$

A serious error has occurred in an internal call. Check all subroutine calls and array sizes. Seek expert help.
 ${\mathbf{ifail}}=99$
An unexpected error has been triggered by this routine. Please
contact
NAG.
See
Section 7 in the Introduction to the NAG Library FL Interface for further information.
 ${\mathbf{ifail}}=399$
Your licence key may have expired or may not have been installed correctly.
See
Section 8 in the Introduction to the NAG Library FL Interface for further information.
 ${\mathbf{ifail}}=999$
Dynamic memory allocation failed.
See
Section 9 in the Introduction to the NAG Library FL Interface for further information.
7
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 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
f11jnf is used in combination with
f11jqf, the more accurate the factorization the fewer iterations will be required. However, the cost of the decomposition will also generally increase.
8
Parallelism and Performance
f11jnf 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 routine. Please also consult the
Users' Note for your implementation for any additional implementationspecific information.
The time taken for a call to f11jnf is roughly proportional to ${{\mathbf{nnzc}}}^{2}/{\mathbf{n}}$.
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
For either method of control, any elements which are not included are discarded if ${\mathbf{mic}}=\text{'N'}$, or subtracted from the diagonal element in the elimination row if ${\mathbf{mic}}=\text{'M'}$.
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}}=\text{'N'}$ 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}}=\text{'M'}$ to see if any improvement can be obtained by using
modified incomplete Cholesky.
f11jnf 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 routine.
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{mic}}=\text{'M'}$.
Although it is not their primary purpose,
f11jnf and
f11jpf may be used together to obtain a
direct solution to a complex Hermitian positive definite linear system. To achieve this the call to
f11jpf should be preceded by a
complete Cholesky factorization
A complete factorization is obtained from a call to
f11jnf 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 illconditioned. 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
f11jnf and
f11jpf as a direct method is illustrated in
f11jpf.
10
Example
This example reads in a complex sparse Hermitian matrix $A$ and calls f11jnf to compute an incomplete Cholesky factorization. It then outputs the nonzero elements of both $A$ and $C=L+{D}^{1}I$.
The call to f11jnf has ${\mathbf{lfill}}=0$, ${\mathbf{mic}}=\text{'N'}$, ${\mathbf{dscale}}=0.0$ and ${\mathbf{pstrat}}=\text{'M'}$, giving an unmodified zerofill factorization of an unperturbed matrix, with Markowitz diagonal pivoting.
10.1
Program Text
10.2
Program Data
10.3
Program Results