NAG Toolbox: nag_sparse_real_symm_precon_ichol (f11ja)

Purpose

Syntax

Description

References

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 Fill-in). 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 fill-in (see Control of Fill-in); 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 fill-in is carried out, using the Markowitz strategy.

$\mathbf{pstrat}=\text{'U'}$

Diagonal pivoting is carried out according to the user-defined 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

   $\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(i-1\right)<\mathbf{irow}\left(i\right)$, or $\mathbf{irow}\left(i-1\right)=\mathbf{irow}\left(i\right)$ and $\mathbf{icol}\left(i-1\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 fill-in 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

Further Comments

Timing

Control of Fill-in

Choice of Arguments

Direct Solution of positive definite Systems

Example

Open in the MATLAB editor: f11ja_example

function f11ja_example


fprintf('f11ja example results\n\n');

% Sparse matrix A
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];


% Incomplete Cholesky factorization, zero fill
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);

% Display details
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