NAG Library Routine Document

f11jaf (real_symm_precon_ichol)

1

Purpose

2

Specification

3

Description

4

References

5

Arguments

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$.

Constraint: $1\le \mathbf{nnz}\le \mathbf{n}\times \left(\mathbf{n}+1\right)/2$.

3:     $\mathbf{a}\left(\mathbf{la}\right)$ – Real (Kind=nag_wp) arrayInput/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 f11zbf 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 as declared in the (sub)program from which f11jaf 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 arrayInput/Output

6:     $\mathbf{icol}\left(\mathbf{la}\right)$ – Integer arrayInput/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 f11zbf):

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

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}$ – 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+\mathbf{dscale}$) at the start of the factorization. This can be used to ensure that the preconditioner is positive definite. See 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 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.

Suggested value: $\mathbf{pstrat}=\text{'M'}$.

Constraint: $\mathbf{pstrat}=\text{'N'}$, $\text{'M'}$ or $\text{'U'}$.

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

On entry: if $\mathbf{pstrat}=\text{'U'}$, $\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].

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

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

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}$ – IntegerOutput

On exit: the number of nonzero elements in the lower triangular matrix $C$.

15:   $\mathbf{npivm}$ – IntegerOutput

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 f11jaf again with an increased value of either lfill or dscale. See also Section 9.4.

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

17:   $\mathbf{liwork}$ – IntegerInput

On entry: the dimension of the array iwork as declared in the (sub)program from which f11jaf 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$;
• if $\mathbf{lfill}<0$, $\mathbf{liwork}\ge \mathbf{la}-\mathbf{nnz}+7\times \mathbf{n}+1$.

18:   $\mathbf{ifail}$ – IntegerInput/Output

On entry: ifail must be set to $0$, $-1\text{ or }1$. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.

For environments where it might be inappropriate to halt program execution when an error is detected, the value $-1\text{ or }1$ is recommended. If the output of error messages is undesirable, then the value $1$ is recommended. Otherwise, if you are not familiar with this argument, the recommended value is $0$. When the value $-\mathbf{1}\text{ 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

$\mathbf{ifail}=1$

On entry, $\mathbf{dtol}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{dtol}\ge 0.0$.

On entry, $\mathbf{la}=〈\mathit{\text{value}}〉$ and $\mathbf{nnz}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{la}\ge 2\times \mathbf{nnz}$.

On entry, liwork is too small: $\mathbf{liwork}=〈\mathit{\text{value}}〉$. Minimum required value of $\mathbf{liwork}=〈\mathit{\text{value}}〉$.

On entry, $\mathbf{mic}\ne \text{'M'}$ or $\text{'N'}$: $\mathbf{mic}=〈\mathit{\text{value}}〉$.

On entry, $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{n}\ge 1$.

On entry, $\mathbf{nnz}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{nnz}\ge 1$.

On entry, $\mathbf{nnz}=〈\mathit{\text{value}}〉$ and $\mathbf{n}=〈\mathit{\text{value}}〉$.
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}=〈\mathit{\text{value}}〉$.

$\mathbf{ifail}=2$

On entry, $\mathbf{a}\left(i\right)$ is out of order: $i=〈\mathit{\text{value}}〉$.

On entry, $\mathit{I}=〈\mathit{\text{value}}〉$, $\mathbf{icol}\left(\mathit{I}\right)=〈\mathit{\text{value}}〉$ and $\mathbf{irow}\left(\mathit{I}\right)=〈\mathit{\text{value}}〉$.
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, $i=〈\mathit{\text{value}}〉$, $\mathbf{irow}\left(i\right)=〈\mathit{\text{value}}〉$ and $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{irow}\left(i\right)\ge 1$ and $\mathbf{irow}\left(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}=〈\mathit{\text{value}}〉$.

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 f11zbf to reorder and sum or remove duplicates.

$\mathbf{ifail}=3$

On entry, a user-supplied value of ipiv is repeated.

On entry, a user-supplied 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 3.9 in How to Use the NAG Library and its Documentation for further information.

$\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

See Section 3.8 in How to Use the NAG Library and its Documentation for further information.

$\mathbf{ifail}=-999$

Dynamic memory allocation failed.

See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7

Accuracy

8

Parallelism and Performance

9

Further Comments

9.1

Timing

9.2

Control of Fill-in

9.3

Choice of Arguments

9.4

Direct Solution of positive definite Systems

10

Example

10.1

Program Text

Program Text (f11jafe.f90)

10.2

Program Data

Program Data (f11jafe.d)

10.3

Program Results

Program Results (f11jafe.r)