PDF version (NAG web site
, 64bit version, 64bit version)
NAG Toolbox: nag_sparse_real_symm_precon_ichol (f11ja)
Purpose
nag_sparse_real_symm_precon_ichol (f11ja) 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
nag_sparse_real_symm_basic_solver (f11ge) or
nag_sparse_real_symm_solve_ichol (f11jc).
Syntax
[
a,
irow,
icol,
ipiv,
istr,
nnzc,
npivm,
ifail] = f11ja(
nz,
a,
irow,
icol,
lfill,
dtol,
mic,
dscale,
ipiv, 'n',
n, 'la',
la, 'pstrat',
pstrat)
[
a,
irow,
icol,
ipiv,
istr,
nnzc,
npivm,
ifail] = nag_sparse_real_symm_precon_ichol(
nz,
a,
irow,
icol,
lfill,
dtol,
mic,
dscale,
ipiv, 'n',
n, 'la',
la, 'pstrat',
pstrat)
Description
nag_sparse_real_symm_precon_ichol (f11ja) computes an incomplete Cholesky factorization (see
Meijerink and Van der Vorst (1977)) of a real sparse symmetric
$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 one of the symmetric iterative solvers
nag_sparse_real_symm_basic_solver (f11ge) or
nag_sparse_real_symm_solve_ichol (f11jc).
The decomposition is written in the form
where
and
$P$ is a permutation matrix,
$L$ is lower triangular with unit diagonal elements,
$D$ is 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
Further Comments.
The sparse matrix
$A$ is represented in symmetric coordinate storage (SCS) format (see
Symmetric coordinate storage (SCS) format 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
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
Parameters
Compulsory Input Parameters
 1:
$\mathrm{nz}$ – int64int32nag_int scalar

The number of nonzero elements in the lower triangular part of the matrix $A$.
Constraint:
$1\le {\mathbf{nz}}\le {\mathbf{n}}\times \left({\mathbf{n}}+1\right)/2$.
 2:
$\mathrm{a}\left({\mathbf{la}}\right)$ – double array

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
nag_sparse_real_symm_sort (f11zb) may be used to order the elements in this way.
 3:
$\mathrm{irow}\left({\mathbf{la}}\right)$ – int64int32nag_int array
 4:
$\mathrm{icol}\left({\mathbf{la}}\right)$ – int64int32nag_int array

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_symm_sort (f11zb)):
 $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{nz}}$;
 ${\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{nz}}$.
 5:
$\mathrm{lfill}$ – int64int32nag_int scalar

If
${\mathbf{lfill}}\ge 0$ its value is the maximum level of fill allowed in the decomposition (see
Control of Fillin). A negative value of
lfill indicates that
dtol will be used to control the fill instead.
 6:
$\mathrm{dtol}$ – double scalar

If
${\mathbf{lfill}}<0$,
dtol is used as a drop tolerance to control the fillin (see
Control of Fillin); otherwise
dtol is not referenced.
Constraint:
if ${\mathbf{lfill}}<0$, ${\mathbf{dtol}}\ge 0.0$.
 7:
$\mathrm{mic}$ – string (length ≥ 1)

Indicates whether or not the factorization should be modified to preserve row sums (see
Choice of s).
 ${\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'}$.
 8:
$\mathrm{dscale}$ – double scalar

The diagonal scaling parameter. All diagonal elements are multiplied by the factor (
$1+{\mathbf{dscale}}$) at the start of the factorization. This can be used to ensure that the preconditioner is positive definite. See
Choice of s.
 9:
$\mathrm{ipiv}\left({\mathbf{n}}\right)$ – int64int32nag_int array

If
${\mathbf{pstrat}}=\text{'U'}$, then
${\mathbf{ipiv}}\left(i\right)$ must specify the row index of the diagonal element 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 [1,
n].
Optional Input Parameters
 1:
$\mathrm{n}$ – int64int32nag_int scalar

Default:
the dimension of the array
ipiv.
$n$, the order of the matrix $A$.
Constraint:
${\mathbf{n}}\ge 1$.
 2:
$\mathrm{la}$ – int64int32nag_int scalar

Default:
the dimension of the arrays
a,
irow,
icol. (An error is raised if these dimensions are not equal.)
The dimension of the arrays
a,
irow and
icol. these arrays must be of sufficient size to store both
$A$ (
nz elements) and
$C$ (
nnzc elements).
Constraint:
${\mathbf{la}}\ge 2\times {\mathbf{nz}}$.
 3:
$\mathrm{pstrat}$ – string (length ≥ 1)
Default:
$\text{'M'}$
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.
 ${\mathbf{pstrat}}=\text{'U'}$
 Diagonal pivoting is carried out according to the userdefined input value of ipiv.
Constraint:
${\mathbf{pstrat}}=\text{'N'}$, $\text{'M'}$ or $\text{'U'}$.
Output Parameters
 1:
$\mathrm{a}\left({\mathbf{la}}\right)$ – double array

The first
nz 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.
 2:
$\mathrm{irow}\left({\mathbf{la}}\right)$ – int64int32nag_int array
 3:
$\mathrm{icol}\left({\mathbf{la}}\right)$ – int64int32nag_int array

The row and column indices of the nonzero elements returned in
a.
 4:
$\mathrm{ipiv}\left({\mathbf{n}}\right)$ – int64int32nag_int array

The pivot indices. If ${\mathbf{ipiv}}\left(i\right)=j$ then the diagonal element in row $j$ was used as the pivot at elimination stage $i$.
 5:
$\mathrm{istr}\left({\mathbf{n}}+1\right)$ – int64int32nag_int array

${\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.
 6:
$\mathrm{nnzc}$ – int64int32nag_int scalar

The number of nonzero elements in the lower triangular matrix $C$.
 7:
$\mathrm{npivm}$ – int64int32nag_int scalar

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
nag_sparse_real_symm_precon_ichol (f11ja) again with an increased value of either
lfill or
dscale. See also
Direct Solution of Systems.
 8:
$\mathrm{ifail}$ – int64int32nag_int scalar
${\mathbf{ifail}}={\mathbf{0}}$ unless the function detects an error (see
Error Indicators and Warnings).
Error Indicators and Warnings
Errors or warnings detected by the function:
 ${\mathbf{ifail}}=1$

On entry,  ${\mathbf{n}}<1$, 
or  ${\mathbf{nz}}<1$, 
or  ${\mathbf{nz}}>{\mathbf{n}}\times \left({\mathbf{n}}+1\right)/2$, 
or  ${\mathbf{la}}<2\times {\mathbf{nz}}$, 
or  ${\mathbf{dtol}}<0.0$, 
or  ${\mathbf{mic}}\ne \text{'M'}$ or $\text{'N'}$, 
or  ${\mathbf{pstrat}}\ne \text{'N'}$, $\text{'M'}$ or $\text{'U'}$, 
or  $\mathit{liwork}<2\times {\mathbf{la}}3\times {\mathbf{nz}}+7\times {\mathbf{n}}+1$, and ${\mathbf{lfill}}\ge 0$, 
or  $\mathit{liwork}<{\mathbf{la}}{\mathbf{nz}}+7\times {\mathbf{n}}+1$, and ${\mathbf{lfill}}<0$. 
 ${\mathbf{ifail}}=2$

On entry, the arrays
irow and
icol fail to satisfy the following constraints:
 $1\le {\mathbf{irow}}\left(i\right)\le {\mathbf{n}}$ and $1\le {\mathbf{icol}}\left(i\right)\le {\mathbf{irow}}\left(i\right)$, for $i=1,2,\dots ,{\mathbf{nz}}$;
 ${\mathbf{irow}}\left(i1\right)<{\mathbf{irow}}\left(i\right)$, or ${\mathbf{irow}}\left(i1\right)={\mathbf{irow}}\left(i\right)$ and ${\mathbf{icol}}\left(i1\right)<{\mathbf{icol}}\left(i\right)$, for $i=2,3,\dots ,{\mathbf{nz}}$.
Therefore 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. Call
nag_sparse_real_symm_sort (f11zb) to reorder and sum or remove duplicates.
 ${\mathbf{ifail}}=3$

On entry,
${\mathbf{pstrat}}=\text{'U'}$, but
ipiv does not represent a valid permutation of the integers in
$\left[1,{\mathbf{n}}\right]$. An input value of
ipiv is either out of range or repeated.
 ${\mathbf{ifail}}=4$

la is too small, resulting in insufficient storage space for fillin elements. The decomposition has been terminated before completion. Either increase
la or reduce the amount of fill by setting
${\mathbf{pstrat}}=\text{'M'}$, reducing
lfill, or increasing
dtol.
 ${\mathbf{ifail}}=5$ (nag_sparse_real_symm_sort (f11zb))

A serious error has occurred in an internal call to the specified function. Check all function calls and array sizes. Seek expert help.
 ${\mathbf{ifail}}=99$
An unexpected error has been triggered by this routine. Please
contact
NAG.
 ${\mathbf{ifail}}=399$
Your licence key may have expired or may not have been installed correctly.
 ${\mathbf{ifail}}=999$
Dynamic memory allocation failed.
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
nag_sparse_real_symm_precon_ichol (f11ja) is used in combination with
nag_sparse_real_symm_basic_solver (f11ge) or
nag_sparse_real_symm_solve_ichol (f11jc), the more accurate the factorization the fewer iterations will be required. However, the cost of the decomposition will also generally increase.
Further Comments
Timing
The time taken for a call to nag_sparse_real_symm_precon_ichol (f11ja) is roughly proportional to ${\left({\mathbf{nnzc}}\right)}^{2}/{\mathbf{n}}$.
Control of Fillin
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'}$.
Choice of Arguments
There is unfortunately no choice of the various algorithmic arguments 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
$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.
nag_sparse_real_symm_precon_ichol (f11ja) 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.
If
$A$ has nonpositive offdiagonal elements, is nonsingular, and has only nonnegative elements in its inverse, it is called an ‘Mmatrix’. It can be shown that no pivot modifications are required in the incomplete Cholesky factorization of an Mmatrix (see
Meijerink and Van der Vorst (1977)). In this case a good preconditioner can generally be expected by setting
${\mathbf{lfill}}=0$,
${\mathbf{mic}}=\text{'M'}$ and
${\mathbf{dscale}}=0.0$.
For certain meshbased problems involving Mmatrices it can be shown in theory that setting
${\mathbf{mic}}=\text{'M'}$, 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
${\mathbf{dscale}}=0.0$, although an improvement in condition can result from increasing
dscale slightly (see
Van der Vorst (1990)).
Some illustrations of the application of
nag_sparse_real_symm_precon_ichol (f11ja) to linear systems arising from the discretization of twodimensional elliptic partial differential equations, and to randomvalued randomly structured symmetric positive definite linear systems, can be found in
Salvini and Shaw (1995).
Direct Solution of positive definite Systems
Although it is not their primary purpose,
nag_sparse_real_symm_precon_ichol (f11ja) and
nag_sparse_real_symm_precon_ichol_solve (f11jb) may be used together to obtain a
direct solution to a symmetric positive definite linear system. To achieve this the call to
nag_sparse_real_symm_precon_ichol_solve (f11jb) should be preceded by a
complete Cholesky factorization
A complete factorization is obtained from a call to
nag_sparse_real_symm_precon_ichol (f11ja) 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
nag_sparse_real_symm_precon_ichol (f11ja) and
nag_sparse_real_symm_precon_ichol_solve (f11jb) as a direct method is illustrated in
Example in
nag_sparse_real_symm_precon_ichol_solve (f11jb).
Example
This example reads in a symmetric sparse matrix $A$ and calls nag_sparse_real_symm_precon_ichol (f11ja) to compute an incomplete Cholesky factorization. It then outputs the nonzero elements of both $A$ and $C=L+{D}^{1}I$.
The call to nag_sparse_real_symm_precon_ichol (f11ja) 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.
Open in the MATLAB editor:
f11ja_example
function f11ja_example
fprintf('f11ja example results\n\n');
n = int64(7);
nz = int64(16);
a = zeros(1000,1);
irow = zeros(1000,1,'int64');
icol = irow;
a(1:16) = [4 1 5 2 2 3 1 1 4 1 2 3 2 1 2 5];
irow(1:16) = [1 2 2 3 4 4 5 5 5 6 6 6 7 7 7 7];
icol(1:16) = [1 1 2 3 2 4 1 4 5 2 5 6 1 2 3 7];
lfill = int64(0);
dtol = 0;
mic = 'N';
dscale = 0;
ipiv = zeros(n, 1, 'int64');
[a, irow, icol, ipiv, istr, nnzc, npivm, ifail] = ...
f11ja( ...
nz, a, irow, icol, lfill, dtol, mic, dscale, ipiv);
fprintf(' Original Matrix\n');
inda = 1:nz;
amat = [inda' a(inda) irow(inda) icol(inda)];
fprintf('n = %4d\n', n);
fprintf('nz = %4d\n', nz);
fprintf('\n a irow icol\n');
fprintf('%4d %11.4f%8d%8d\n',amat');
fprintf('\n Factorization\n');
inda = nz+1:nz+nnzc;
amat = [inda' a(inda) irow(inda) icol(inda)];
fprintf('n = %4d\n', n);
fprintf('nz = %4d\n', nnzc);
fprintf('npivm = %4d\n', npivm);
fprintf('\n a irow icol\n');
fprintf('%4d %11.4f%8d%8d\n',amat');
fprintf('\n i ipiv(i)\n');
fprintf('%4d %8d\n',[[1:n]'; ipiv]);
f11ja example results
Original Matrix
n = 7
nz = 16
a irow icol
1 4.0000 1 1
2 1.0000 2 1
3 5.0000 2 2
4 2.0000 3 3
5 2.0000 4 2
6 3.0000 4 4
7 1.0000 5 1
8 1.0000 5 4
9 4.0000 5 5
10 1.0000 6 2
11 2.0000 6 5
12 3.0000 6 6
13 2.0000 7 1
14 1.0000 7 2
15 2.0000 7 3
16 5.0000 7 7
Factorization
n = 7
nz = 16
npivm = 0
a irow icol
17 1.0000 1 1
18 0.0000 2 2
19 0.0000 3 2
20 0.0000 3 3
21 1.0000 4 3
22 1.0000 4 4
23 0.0000 5 3
24 0.0000 5 5
25 1.0000 6 2
26 1.0000 6 4
27 0.0000 6 5
28 0.0000 6 6
29 1.0000 7 1
30 1.0000 7 5
31 1.0000 7 6
32 1.0000 7 7
i ipiv(i)
1 2
3 4
5 6
7 3
4 5
6 1
2 7
PDF version (NAG web site
, 64bit version, 64bit version)
© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2015