NAG Library Routine Document

F01BRF

1  Purpose

2  Specification

3  Description

4  References

5  Parameters

1:     $\mathrm{N}$ – INTEGERInput

On entry: $n$, the order of the matrix $A$.

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

2:     $\mathrm{NZ}$ – INTEGERInput

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

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

3:     $\mathrm{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 F01BRF will reorder them.

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

4:     $\mathrm{LICN}$ – INTEGERInput

On entry: the dimension of the arrays A and ICN as declared in the (sub)program from which F01BRF is called. Since the factorization is returned in A and ICN, LICN should be large enough to accommodate this and should ordinarily be $2$ to $4$ times as large as NZ.

Constraint: $\mathbf{LICN}\ge \mathbf{NZ}$.

5:     $\mathrm{IRN}\left(\mathbf{LIRN}\right)$ – INTEGER arrayInput/Output

On entry: $\mathbf{IRN}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{NZ}$, must contain the row index of the nonzero element stored in $\mathbf{A}\left(i\right)$.

On exit: IRN is overwritten and is not needed for subsequent calls of F01BSF or F04AXF.

6:     $\mathrm{LIRN}$ – INTEGERInput

On entry: the dimension of the array IRN as declared in the (sub)program from which F01BRF is called. It need not be as large as LICN; normally it will not need to be very much greater than NZ.

Constraint: $\mathbf{LIRN}\ge \mathbf{NZ}$.

7:     $\mathrm{ICN}\left(\mathbf{LICN}\right)$ – INTEGER arrayCommunication Array

$\mathbf{ICN}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{NZ}$, must contain, on entry, the column index of the nonzero element stored in $\mathbf{A}\left(i\right)$. ICN contains, on exit, the column indices of the nonzero elements in the factorization. The array must not be changed by you between a call of F01BRF and subsequent calls of F01BSF or F04AXF.

8:     $\mathrm{PIVOT}$ – REAL (KIND=nag_wp)Input

On entry: should have a value in the range $0.0\le \mathbf{PIVOT}\le 0.9999$ and is used to control the choice of pivots. If $\mathbf{PIVOT}<0.0$, the value $0.0$ is assumed, and if $\mathbf{PIVOT}>0.9999$, the value $0.9999$ is assumed. When searching a row for a pivot, any element is excluded which is less than PIVOT times the largest of those elements in the row available as pivots. Thus decreasing PIVOT biases the algorithm to maintaining sparsity at the expense of stability.

Suggested value: $\mathbf{PIVOT}=0.1$ has been found to work well on test examples.

9:     $\mathrm{IKEEP}\left(5\times \mathbf{N}\right)$ – INTEGER arrayCommunication Array

On exit: indexing information about the factorization.

You must not change IKEEP between a call of F01BRF and subsequent calls to F01BSF or F04AXF.

10:   $\mathrm{IW}\left(8\times \mathbf{N}\right)$ – INTEGER arrayWorkspace

11:   $\mathrm{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.

12:   $\mathrm{LBLOCK}$ – LOGICALInput

On entry: if $\mathbf{LBLOCK}=\mathrm{.TRUE.}$, the matrix is preordered into block lower triangular form before the $LU$ factorization is performed; otherwise the entire matrix is factorized.

Suggested value: $\mathbf{LBLOCK}=\mathrm{.TRUE.}$ unless the matrix is known to be irreducible, or is singular and an upper bound on the rank is required.

13:   $\mathrm{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.2), 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 parameter PIVOT for subsequent runs (see Section 7).

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

14:   $\mathrm{ABORT}\left(4\right)$ – LOGICAL arrayInput

On entry: if $\mathbf{ABORT}\left(1\right)=\mathrm{.TRUE.}$, F01BRF will exit immediately on detecting a structural singularity (one that depends on the pattern of nonzeros) and return $\mathbf{IFAIL}=\mathbf{1}$; otherwise it will complete the factorization (see Section 9.3).

If $\mathbf{ABORT}\left(2\right)=\mathrm{.TRUE.}$, F01BRF will exit immediately on detecting a numerical singularity (one that depends on the numerical values) and return $\mathbf{IFAIL}=\mathbf{2}$; otherwise it will complete the factorization (see Section 9.3).

If $\mathbf{ABORT}\left(3\right)=\mathrm{.TRUE.}$, F01BRF will exit immediately (with $\mathbf{IFAIL}=\mathbf{5}$) when the arrays A and ICN are filled up by the previously factorized, active and unfactorized parts of the matrix; otherwise it continues so that better guidance on necessary array sizes can be given in $\mathbf{IDISP}\left(6\right)$ and $\mathbf{IDISP}\left(7\right)$, and will exit with IFAIL in the range $4$ to $6$. Note that there is always an immediate error exit if the array IRN is too small.

If $\mathbf{ABORT}\left(4\right)=\mathrm{.TRUE.}$, F01BRF exits immediately (with $\mathbf{IFAIL}=\mathbf{13}$) if it finds duplicate elements in the input matrix.

If $\mathbf{ABORT}\left(4\right)=\mathrm{.FALSE.}$, F01BRF 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 values:

• $\mathbf{ABORT}\left(1\right)=\mathrm{.TRUE.}$;
• $\mathbf{ABORT}\left(2\right)=\mathrm{.TRUE.}$;
• $\mathbf{ABORT}\left(3\right)=\mathrm{.FALSE.}$;
• $\mathbf{ABORT}\left(4\right)=\mathrm{.TRUE.}$.

15:   $\mathrm{IDISP}\left(10\right)$ – INTEGER arrayCommunication Array

On exit: contains information about the factorization.

$\mathbf{IDISP}\left(1\right)$ and $\mathbf{IDISP}\left(2\right)$ indicate the position in arrays A and ICN of the first and last elements in the $LU$ factorization of the diagonal blocks. ($\mathbf{IDISP}\left(2\right)$ gives the number of nonzeros in the factorization.) $\mathbf{IDISP}\left(1\right)$ and $\mathbf{IDISP}\left(2\right)$ must not be changed by you between a call of F01BRF and subsequent calls to F01BSF or F04AXF.

$\mathbf{IDISP}\left(3\right)$ and $\mathbf{IDISP}\left(4\right)$ monitor the adequacy of ‘elbow room’ in the arrays IRN and A (and ICN) respectively, by giving the number of times that the data in these arrays has been compressed during the factorization to release more storage. If either $\mathbf{IDISP}\left(3\right)$ or $\mathbf{IDISP}\left(4\right)$ is quite large (say greater than $10$), it will probably pay you to increase the size of the corresponding array(s) for subsequent runs. If either is very low or zero, then you can perhaps save storage by reducing the size of the corresponding array(s).

$\mathbf{IDISP}\left(5\right)$, when $\mathbf{LBLOCK}=\mathrm{.FALSE.}$, gives an upper bound on the rank of the matrix; when $\mathbf{LBLOCK}=\mathrm{.TRUE.}$, gives an upper bound on the sum of the ranks of the lower triangular blocks.

$\mathbf{IDISP}\left(6\right)$ and $\mathbf{IDISP}\left(7\right)$ give the minimum size of arrays IRN and A (and ICN) respectively which would enable a successful run on an identical matrix (but some ‘elbow-room’ should be allowed – see Section 9).

$\mathbf{IDISP}\left(8\right)$ to $\left(10\right)$ are only used if $\mathbf{LBLOCK}=\mathrm{.TRUE.}$.

• $\mathbf{IDISP}\left(8\right)$ gives the structural rank of the matrix.
• $\mathbf{IDISP}\left(9\right)$ gives the number of diagonal blocks.
• $\mathbf{IDISP}\left(10\right)$ gives the size of the largest diagonal block.

You must not change IDISP between a call of F01BRF and subsequent calls to F01BSF or F04AXF.

16:   $\mathrm{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.3 in the Essential Introduction).

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}=-2$

Successful factorization of a numerically singular matrix (which may also be structurally singular) (see Section 9.3).

$\mathbf{IFAIL}=-1$

Successful factorization of a structurally singular matrix (see Section 9.3).

$\mathbf{IFAIL}=1$

The matrix is structurally singular and the factorization has been abandoned ($\mathbf{ABORT}\left(1\right)$ was .TRUE. on entry).

$\mathbf{IFAIL}=2$

The matrix is numerically singular and the factorization has been abandoned ($\mathbf{ABORT}\left(2\right)$ was .TRUE. on entry).

$\mathbf{IFAIL}=3$

LIRN is too small: there is not enough space in the array IRN to continue the factorization. You are recommended to try again with LIRN (and the length of IRN) equal to at least $\mathbf{IDISP}\left(6\right)+\mathbf{N}/2$.

$\mathbf{IFAIL}=4$

LICN is much too small: there is much too little space in the arrays A and ICN to continue the factorization.

$\mathbf{IFAIL}=5$

LICN is too small: there is not enough space in the arrays A and ICN to store the factorization. If $\mathbf{ABORT}\left(3\right)$ was .FALSE. on entry, the factorization has been completed but some of the $LU$ factors have been discarded to create space; $\mathbf{IDISP}\left(7\right)$ then gives the minimum value of LICN (i.e., the minimum length of A and ICN) required for a successful factorization of the same matrix.

$\mathbf{IFAIL}=6$

LICN and LIRN are both too small: effectively this is a combination of $\mathbf{IFAIL}=\mathbf{3}$ and $\mathbf{5}$ (with $\mathbf{ABORT}\left(3\right)=\mathrm{.FALSE.}$).

$\mathbf{IFAIL}=7$

LICN is too small: there is not enough space in the arrays A and ICN for the permutation to block triangular form.

$\mathbf{IFAIL}=8$

On entry,

$\mathbf{N}\le 0$.

$\mathbf{IFAIL}=9$

On entry,

$\mathbf{NZ}\le 0$.

$\mathbf{IFAIL}=10$

On entry,

$\mathbf{LICN}<\mathbf{NZ}$.

$\mathbf{IFAIL}=11$

On entry,

$\mathbf{LIRN}<\mathbf{NZ}$.

$\mathbf{IFAIL}=12$

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

$\mathbf{IFAIL}=13$

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

$\mathbf{IFAIL}=-99$

An unexpected error has been triggered by this routine. Please contact NAG.

See Section 3.8 in the Essential Introduction for further information.

$\mathbf{IFAIL}=-399$

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

See Section 3.7 in the Essential Introduction for further information.

$\mathbf{IFAIL}=-999$

Dynamic memory allocation failed.

See Section 3.6 in the Essential Introduction for further information.

7  Accuracy

8  Parallelism and Performance

9  Further Comments

9.1  Timing

9.2  Scaling

9.3  Singular and Rectangular Systems

9.4  Duplicated Nonzeros

9.5  Determinant

   DET = 1.0
   ID = IDISP(1)
   DO 10 I = 1, N
      IDG = ID + IKEEP(3*N+I)
      DET = DET*A(IDG)
      IF (IKEEP(N+I).NE.I)DET = -DET
      IF (IKEEP(2*N+I).NE.I)DET = -DET
      ID = ID + IKEEP(I)
10 CONTINUE

10  Example

10.1  Program Text

Program Text (f01brfe.f90)

10.2  Program Data

Program Data (f01brfe.d)

10.3  Program Results

Program Results (f01brfe.r)