NAG FL Interface
f01lhf (real_​gen_​blkdiag_​lu)

1 Purpose

2 Specification

3 Description

f01lhf factorizes a real almost block diagonal matrix, $A$, by row elimination with alternate row and column pivoting such that no ‘fill-in’ is produced. The code, which is derived from ARCECO described in Diaz et al. (1983), uses Level 1 and Level 2 BLAS. No three successive diagonal blocks may have columns in common and therefore the almost block diagonal matrix must have the form shown in the following diagram:

Figure 1

4 References

5 Arguments

1: $\mathbf{n}$ – Integer Input

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

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

2: $\mathbf{nbloks}$ – Integer Input

On entry: $n$, the total number of blocks of the matrix $A$.

Constraint: $0<\mathbf{nbloks}\le \mathbf{n}$.

3: $\mathbf{blkstr}\left(3,\mathbf{nbloks}\right)$ – Integer array Input

On entry: information which describes the block structure of $A$ as follows:

• $\mathbf{blkstr}\left(1,k\right)$ must contain the number of rows in the $k$th block, $k=1,2,\dots ,\mathbf{nbloks}$;
• $\mathbf{blkstr}\left(2,k\right)$ must contain the number of columns in the $k$th block, $k=1,2,\dots ,\mathbf{nbloks}$;
• $\mathbf{blkstr}\left(3,k\right)$ must contain the number of columns of overlap between the $k$th and $\left(k+1\right)$th blocks, $k=1,2,\dots ,\mathbf{nbloks}-1$. $\mathbf{blkstr}\left(3,\mathbf{nbloks}\right)$ need not be set.

The following conditions delimit the structure of $A$:

• $\mathbf{blkstr}\left(1,k\right),\mathbf{blkstr}\left(2,k\right)>0\text{, \hspace{1em}}k=1,2,\dots ,\mathbf{nbloks}$,
• $\mathbf{blkstr}\left(3,k\right)\ge 0\text{, \hspace{1em}}k=1,2,\dots ,\mathbf{nbloks}-1$,

(there must be at least one column and one row in each block and a non-negative number of columns of overlap);

• $\mathbf{blkstr}\left(3,k-1\right)+\mathbf{blkstr}\left(3,k\right)\le \mathbf{blkstr}\left(2,k\right)\text{, \hspace{1em}}k=2,3,\dots ,\mathbf{nbloks}-1$,

(the total number of columns in overlaps in each block must not exceed the number of columns in that block);

• $\mathbf{blkstr}\left(2,1\right)\ge \mathbf{blkstr}\left(1,1\right)$,
• $\mathbf{blkstr}\left(2,1\right)+{\displaystyle \sum _{k=2}^j}\left[\mathbf{blkstr}\left(2,k\right)-\mathbf{blkstr}\left(3,k-1\right)\right]\ge {\displaystyle \sum _{k=1}^j}\mathbf{blkstr}\left(1,k\right)$, $j=2,3,\dots ,\mathbf{nbloks}-1$,
• ${\displaystyle \sum _{k=1}^j}\left[\mathbf{blkstr}\left(2,k\right)-\mathbf{blkstr}\left(3,k\right)\right]\le {\displaystyle \sum _{k=1}^j}\mathbf{blkstr}\left(1,k\right)\text{, \hspace{1em}}j=1,2,\dots ,\mathbf{nbloks}-1$,

(the index of the first column of the overlap between the $j$th and $\left(j+1\right)$th blocks must be $\le$ the index of the last row of the $j$th block, and the index of the last column of overlap must be $\ge$ the index of the last row of the $j$th block);

• ${\displaystyle \sum _{k=1}^{\mathbf{nbloks}}}\mathbf{blkstr}\left(1,k\right)=n$,
• $\mathbf{blkstr}\left(2,1\right)+{\displaystyle \sum _{k=2}^{\mathbf{nbloks}}}\left[\mathbf{blkstr}\left(2,k\right)-\mathbf{blkstr}\left(3,k-1\right)\right]=nk$,

(both the number of rows and the number of columns of $A$ must equal $n$).

4: $\mathbf{a}\left(\mathbf{lena}\right)$ – Real (Kind=nag_wp) array Input/Output

On entry: the elements of the almost block diagonal matrix stored block by block, with each block stored column by column. The sizes of the blocks and the overlaps are defined by the argument blkstr.

If $a_{rs}$ is the first element in the $k$th block, then an arbitrary element $a_{ij}$ in the $k$th block must be stored in the array element:

$$\mathbf{a}\left(p_k+\left(j-r\right)m_k+\left(i-s\right)+1\right)$$

where

$$p_k=\sum _{l=1}^{k-1}\mathbf{blkstr}\left(1,l\right)\times \mathbf{blkstr}\left(2,l\right)$$

is the base address of the $k$th block, and

$$m_k=\mathbf{blkstr}\left(1,k\right)$$

is the number of rows of the $k$th block.

See Section 9 for comments on scaling.

On exit: the factorized form of the matrix.

5: $\mathbf{lena}$ – Integer Input

On entry: the dimension of the array a as declared in the (sub)program from which f01lhf is called.

Constraint: $\mathbf{lena}\ge {\displaystyle \sum _{k=1}^{\mathbf{nbloks}}}\left[\mathbf{blkstr}\left(1,k\right)\times \mathbf{blkstr}\left(2,k\right)\right]$.

6: $\mathbf{pivot}\left(\mathbf{n}\right)$ – Integer array Output

On exit: details of the interchanges.

7: $\mathbf{tol}$ – Real (Kind=nag_wp) Input/Output

On entry: a relative tolerance to be used to indicate whether or not the matrix is singular. For a discussion on how tol is used see Section 9. If tol is non-positive, tol is reset to $10\epsilon$, where $\epsilon$ is the machine precision.

On exit: unchanged unless $\mathbf{tol}\le 0.0$ on entry, in which case it is set to $10\epsilon$.

8: $\mathbf{kpivot}$ – Integer Output

On exit: if $\mathbf{ifail}=\mathbf{2}$, kpivot contains the value $k$, where $k$ is the first position on the diagonal of the matrix $A$ where too small a pivot was detected. Otherwise kpivot is set to $0$.

9: $\mathbf{ifail}$ – Integer Input/Output

On entry: ifail must be set to $0$, $-1$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.

A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $-1$ means that an error message is printed while a value of $1$ means that it is not.

If halting is not appropriate, the value $-1$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $0$ is recommended. When the value $-\mathbf{1}$ 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, $K=〈\mathit{\text{value}}〉$, $\mathbf{blkstr}\left(2,K\right)=〈\mathit{\text{value}}〉$ and $\mathbf{blkstr}\left(1,K\right)=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{blkstr}\left(2,K\right)\ge \mathbf{blkstr}\left(1,K\right)$.

On entry, $K=〈\mathit{\text{value}}〉$, $\mathbf{blkstr}\left(2,K\right)=〈\mathit{\text{value}}〉$ $\mathbf{blkstr}\left(3,K\right)=〈\mathit{\text{value}}〉$ and $\mathbf{blkstr}\left(1,K\right)=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{blkstr}\left(2,K\right)-\mathbf{blkstr}\left(3,K\right)\le \mathbf{blkstr}\left(1,K\right)$.

On entry, $K=〈\mathit{\text{value}}〉$ and $\mathbf{blkstr}\left(1,K\right)=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{blkstr}\left(1,K\right)\ge 1$.

On entry, $K=〈\mathit{\text{value}}〉$ and $\mathbf{blkstr}\left(2,K\right)=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{blkstr}\left(2,K\right)\ge 1$.

On entry, $K=〈\mathit{\text{value}}〉$ and $\mathbf{blkstr}\left(3,K\right)=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{blkstr}\left(3,K\right)\ge 0$.

On entry, $K=〈\mathit{\text{value}}〉$ $\mathbf{blkstr}\left(3,K\right)=〈\mathit{\text{value}}〉$ $\mathbf{blkstr}\left(3,K-1\right)=〈\mathit{\text{value}}〉$ and $\mathbf{blkstr}\left(2,K\right)=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{blkstr}\left(3,K\right)+\mathbf{blkstr}\left(3,K-1\right)\ge \mathbf{blkstr}\left(2,K\right)$.

On entry, lena is too small. $\mathbf{lena}=〈\mathit{\text{value}}〉$. Minimum possible dimension: $〈\mathit{\text{value}}〉$.

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

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

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

On entry, the following equality does not hold: $\mathbf{blkstr}\left(2,1\right)+\mathrm{sum}\left(\mathbf{blkstr}\left(2,k\right)-\mathbf{blkstr}\left(3,k-1\right):k=2,\mathbf{nbloks}\right)=\mathbf{n}$.

On entry, the following equality does not hold: $\mathrm{sum}\left(\mathbf{blkstr}\left(1,k\right):k=1,\mathbf{nbloks}\right)=\mathbf{n}$.

On entry, the following inequality was not satisfied for: $J=〈\mathit{\text{value}}〉$. $\mathrm{sum}\left(\mathbf{blkstr}\left(2,k\right)-\mathbf{blkstr}\left(3,k\right):k=1,J\right)\le$ $\mathrm{sum}\left(\mathbf{blkstr}\left(1,k\right):k=1,J\right)\le$ $\mathbf{blkstr}\left(2,1\right)+\mathrm{sum}\left(\mathbf{blkstr}\left(2,k\right)-\mathbf{blkstr}\left(3,k-1\right):k=2,J\right)$.

$\mathbf{ifail}=2$

Factorization completed, but pivot in diagonal $I$ was small: $I=〈\mathit{\text{value}}〉$.

$\mathbf{ifail}=-99$

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

See Section 7 in the Introduction to the NAG Library FL Interface for further information.

$\mathbf{ifail}=-399$

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

See Section 8 in the Introduction to the NAG Library FL Interface for further information.

$\mathbf{ifail}=-999$

Dynamic memory allocation failed.

See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results