NAG FL Interface
f11yef (sym_​rcm)

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

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

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

Constraint: $\mathbf{n}\ge 1$.

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

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

Constraint: $\mathbf{nnz}\ge 0$.

3: $\mathbf{icolzp}\left(\mathbf{n}+1\right)$ – Integer array Input

On entry: icolzp records the index into irowix which starts each new column.

Constraints:

• $1\le \mathbf{icolzp}\left(\mathit{i}\right)\le \mathbf{nnz}+1$, for $\mathit{i}=2,3,\dots ,\mathbf{n}$;
• $\mathbf{icolzp}\left(1\right)=1$;
• $\mathbf{icolzp}\left(\mathbf{n}+1\right)=\mathbf{nnz}+1$, where $\mathbf{icolzp}\left(i\right)$ holds the position integer for the starts of the columns in irowix.

4: $\mathbf{irowix}\left(\mathbf{nnz}\right)$ – Integer array Input

On entry: the row indices corresponding to the nonzero elements in the matrix $A$.

Constraint: $1\le \mathbf{irowix}\left(\mathit{i}\right)\le \mathbf{n}$, for $\mathit{i}=1,2,\dots ,\mathbf{nnz}$.

5: $\mathbf{lopts}\left(5\right)$ – Logical array Input

On entry: the options to be used by f11yef.

$\mathbf{lopts}\left(1\right)=\mathrm{.TRUE.}$

Row/column $i$ of the matrix $A$ will only be referenced if $\mathbf{mask}\left(i\right)\ne 0$, otherwise $\mathbf{mask}$ will be ignored.

$\mathbf{lopts}\left(2\right)=\mathrm{.TRUE.}$

The final permutation will not be reversed, that is, the Cuthill–McKee ordering will be returned. The bandwidth of the non-reversed matrix will be the same but the profile will be the same or larger (see Wai-Hung and Sherman (1976)).

$\mathbf{lopts}\left(3\right)=\mathrm{.TRUE.}$

The matrix $A$ will be checked for symmetrical sparsity pattern, otherwise not.

$\mathbf{lopts}\left(4\right)=\mathrm{.TRUE.}$

The bandwidth and profile of the unpermuted matrix will be calculated, otherwise not.

$\mathbf{lopts}\left(5\right)=\mathrm{.TRUE.}$

The bandwidth and profile of the permuted matrix will be calculated, otherwise not.

6: $\mathbf{mask}\left(*\right)$ – Integer array Input

Note: the dimension of the array mask must be at least $\mathbf{n}$ if $\mathbf{lopts}\left(1\right)=\mathrm{.TRUE.}$, and at least $0$ otherwise.

On entry: mask is only referenced if $\mathbf{lopts}\left(1\right)$ is .TRUE.. A value of $\mathbf{mask}\left(i\right)=0$ indicates that the node corresponding to row or column $i$ is not to be referenced. A value of $\mathbf{mask}\left(i\right)\ne 0$ indicates that the node corresponding to row or column $i$ is to be referenced. In particular, rows and columns not referenced will not be permuted.

7: $\mathbf{perm}\left(\mathbf{n}\right)$ – Integer array Output

On exit: this will contain the permutation vector that describes the permutation matrix $P$ for the reordering of the matrix $A$. The elements of the permutation matrix $P$ are zero except for the unit elements in row $i$ and column $\mathbf{perm}\left(i\right)$, $i=1,2,\dots n$.

8: $\mathbf{info}\left(4\right)$ – Integer array Output

On exit: statistics about the matrix $A$ and the permuted matrix. The quantities below are calculated using any masking in effect otherwise the value zero is returned.

$\mathbf{info}\left(1\right)$

The bandwidth of the matrix $A$, if $\mathbf{lopts}\left(4\right)=\mathrm{.TRUE.}$.

$\mathbf{info}\left(2\right)$

The profile of the matrix $A$, if $\mathbf{lopts}\left(4\right)=\mathrm{.TRUE.}$.

$\mathbf{info}\left(3\right)$

The bandwidth of the permuted matrix $PA{P}^{\mathrm{T}}$, if $\mathbf{lopts}\left(5\right)=\mathrm{.TRUE.}$.

$\mathbf{info}\left(4\right)$

The profile of the permuted matrix $PA{P}^{\mathrm{T}}$, if $\mathbf{lopts}\left(5\right)=\mathrm{.TRUE.}$.

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, $\mathbf{n}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{n}\ge 1$.

$\mathbf{ifail}=2$

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

$\mathbf{ifail}=3$

On entry, $\mathbf{irowix}\left(⟨\mathit{\text{value}}⟩\right)=⟨\mathit{\text{value}}⟩$ and $\mathbf{n}=⟨\mathit{\text{value}}⟩$.
Constraint: $1\le \mathbf{irowix}\left(i\right)\le \mathbf{n}$ for all $i$.

$\mathbf{ifail}=4$

On entry, $\mathbf{icolzp}\left(⟨\mathit{\text{value}}⟩\right)=⟨\mathit{\text{value}}⟩$ and $\mathbf{nnz}=⟨\mathit{\text{value}}⟩$.
Constraint: $1\le \mathbf{icolzp}\left(i\right)\le \mathbf{nnz}$ for all $i$.

$\mathbf{ifail}=5$

On entry, $\mathbf{icolzp}\left(1\right)=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{icolzp}\left(1\right)=1$.

On entry, $\mathbf{icolzp}\left(\mathbf{n}+1\right)=⟨\mathit{\text{value}}⟩$ and $\mathbf{nnz}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{icolzp}\left(\mathbf{n}+1\right)=\mathbf{nnz}+1$.

$\mathbf{ifail}=6$

On entry, the matrix $A$ is not symmetric.
Element $(⟨\mathit{\text{value}}⟩,⟨\mathit{\text{value}}⟩)$ has no symmetric element.

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