NAG Library Routine Document

f01bsf  (real_gen_sparse_lu_reuse)

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

2:     $\mathbf{nz}$ – IntegerInput

On entry: the number of nonzero elements in the matrix $A$.

Constraint: $\mathbf{nz}>0$.

3:     $\mathbf{a}\left(\mathbf{licn}\right)$ – Real (Kind=nag_wp) arrayInput/Output

On entry: $\mathbf{a}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{nz}$, must contain the nonzero elements of the sparse matrix $A$. They can be in any order since f01bsf will reorder them.

On exit: the nonzero elements in the $LU$ factorization. The array must not be changed by you between a call of f01bsf and a call of f04axf.

4:     $\mathbf{licn}$ – IntegerInput

On entry: the dimension of the arrays a and icn as declared in the (sub)program from which f01bsf is called. It should have the same value as it had for f01brf.

Constraint: $\mathbf{licn}\ge \mathbf{nz}$.

5:     $\mathbf{ivect}\left(\mathbf{nz}\right)$ – Integer arrayInput

6:     $\mathbf{jvect}\left(\mathbf{nz}\right)$ – Integer arrayInput

On entry: $\mathbf{ivect}\left(\mathit{i}\right)$ and $\mathbf{jvect}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{nz}$, must contain the row index and the column index respectively of the nonzero element stored in $\mathbf{a}\left(i\right)$.

7:     $\mathbf{icn}\left(\mathbf{licn}\right)$ – Integer arrayInput

icn contains, on entry, the same information as output by f01brf. It must not be changed by you between a call of f01bsf and a call of f04axf.

icn is used as internal workspace prior to being restored on exit and hence is unchanged.

8:     $\mathbf{ikeep}\left(5\times \mathbf{n}\right)$ – Integer arrayCommunication Array

On entry: the same indexing information about the factorization as output in ikeep by f01brf.

You must not change ikeep between a call of f01bsf and subsequent calls to f04axf.

9:     $\mathbf{iw}\left(5\times \mathbf{n}\right)$ – Integer arrayWorkspace

10:   $\mathbf{w}\left(\mathbf{n}\right)$ – Real (Kind=nag_wp) arrayOutput

On exit: if $\mathbf{grow}=\mathrm{.TRUE.}$, $\mathbf{w}\left(1\right)$ contains an estimate (an upper bound) of the increase in size of elements encountered during the factorization (see grow); the rest of the array is used as workspace.

If $\mathbf{grow}=\mathrm{.FALSE.}$, the array is not used.

11:   $\mathbf{grow}$ – LogicalInput

On entry: if $\mathbf{grow}=\mathrm{.TRUE.}$, then on exit $\mathbf{w}\left(1\right)$ contains an estimate (an upper bound) of the increase in size of elements encountered during the factorization. If the matrix is well-scaled (see Section 9), then a high value for $\mathbf{w}\left(1\right)$ indicates that the $LU$ factorization may be inaccurate and you should be wary of the results and perhaps increase the argument pivot for subsequent runs (see Section 7).

12:   $\mathbf{eta}$ – Real (Kind=nag_wp)Input

On entry: the relative pivot threshold below which an error diagnostic is provoked and ifail is set to $\mathbf{ifail}=\mathbf{7}$. If eta is greater than $1.0$, then no check on pivot size is made.

Suggested value: $\mathbf{eta}={10}^{-4}$.

13:   $\mathbf{rpmin}$ – Real (Kind=nag_wp)Output

On exit: if eta is less than $1.0$, then rpmin gives the smallest ratio of the pivot to the largest element in the row of the corresponding upper triangular factor thus monitoring the stability of the factorization. If rpmin is very small it may be advisable to perform a new factorization using f01brf.

14:   $\mathbf{abort}$ – LogicalInput

On entry: if $\mathbf{abort}=\mathrm{.TRUE.}$, f01bsf exits immediately (with $\mathbf{ifail}=\mathbf{8}$) if it finds duplicate elements in the input matrix.

If $\mathbf{abort}=\mathrm{.FALSE.}$, f01bsf proceeds using a value equal to the sum of the duplicate elements.

In either case details of each duplicate element are output on the current advisory message unit (see x04abf), unless suppressed by the value of ifail on entry.

Suggested value: $\mathbf{abort}=\mathrm{.TRUE.}$.

15:   $\mathbf{idisp}\left(2\right)$ – Integer arrayCommunication Array

On entry: $\mathbf{idisp}\left(1\right)$ and $\mathbf{idisp}\left(2\right)$ must be as output in idisp by the previous call of f01brf.

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

For this routine, the normal use of ifail is extended to control the printing of error and warning messages as well as specifying hard or soft failure (see Section 3.4 in How to Use the NAG Library and its Documentation).

On entry: ifail must be set to a value with the decimal expansion $\mathit{cba}$, where each of the decimal digits $c$, $b$ and $a$ must have a value of $0$ or $1$.

$a=0$	specifies hard failure, otherwise soft failure;
$b=0$	suppresses error messages, otherwise error messages will be printed (see Section 6);
$c=0$	suppresses warning messages, otherwise warning messages will be printed (see Section 6).

The recommended value for inexperienced users is $110$ (i.e., hard failure with all messages printed).

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{n}\le 0$.

$\mathbf{ifail}=2$

On entry,

$\mathbf{nz}\le 0$.

$\mathbf{ifail}=3$

On entry,

$\mathbf{licn}<\mathbf{nz}$.

$\mathbf{ifail}=4$

On entry, an element of the input matrix has a row or column index (i.e., an element of ivect or jvect) outside the range $1$ to n.

$\mathbf{ifail}=5$

The input matrix is incompatible with the matrix factorized by the previous call of f01brf (see Section 9).

$\mathbf{ifail}=6$

The input matrix is numerically singular.

$\mathbf{ifail}=7$

A very small pivot has been detected (see Section 5, eta). The factorization has been completed but is potentially unstable.

$\mathbf{ifail}=8$

Duplicate elements have been found in the input matrix and the factorization has been abandoned ($\mathbf{abort}=\mathrm{.TRUE.}$ on entry).

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

10

Example

10.1

Program Text

Program Text (f01bsfe.f90)

10.2

Program Data

Program Data (f01bsfe.d)

10.3

Program Results

Program Results (f01bsfe.r)