NAG Library Function Document

nag_superlu_column_permutation (f11mdc)

1  Purpose

2  Specification

3  Description

4  References

5  Arguments

1:     spec – Nag_ColumnPermutationTypeInput

On entry: indicates the permutation to be applied.

$\mathbf{spec}=\mathrm{Nag\_Sparse\_Identity}$

The identity permutation is used (i.e., the columns are not permuted).

$\mathbf{spec}=\mathrm{Nag\_Sparse\_User}$

The permutation in the iprm array is used, as supplied by you.

$\mathbf{spec}=\mathrm{Nag\_Sparse\_Colamd}$

The permutation computed by the COLAMD algorithm is used

Constraint: $\mathbf{spec}=\mathrm{Nag\_Sparse\_Identity}$, $\mathrm{Nag\_Sparse\_User}$ or $\mathrm{Nag\_Sparse\_Colamd}$.

2:     n – IntegerInput

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

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

3:     icolzp[$\mathit{dim}$] – const IntegerInput

Note: the dimension, dim, of the array icolzp must be at least $\mathbf{n}+1$.

On entry: $\mathbf{icolzp}\left[i-1\right]$ contains the index in $A$ of the start of a new column. See Section 2.1.3 in the f11 Chapter Introduction.

4:     irowix[$\mathit{dim}$] – const IntegerInput

Note: the dimension, dim, of the array irowix must be at least $\mathbf{icolzp}\left[\mathbf{n}\right]-1$, the number of nonzeros of the sparse matrix $A$.

On entry: $\mathbf{irowix}\left[i-1\right]$ contains the row index in $A$ for element $A\left(i\right)$. See Section 2.1.3 in the f11 Chapter Introduction.

5:     iprm[$7\times \mathbf{n}$] – IntegerInput/Output

On entry: the first $\mathbf{n}$ entries contain the column permutation supplied by you. This will be used if $\mathbf{spec}=\mathrm{Nag\_Sparse\_User}$, and ignored otherwise. If used, it must consist of a permutation of all the integers in the range $\left[0,\left(\mathbf{n}-1\right)\right]$, the leftmost column of the matrix $A$ denoted by $0$ and the rightmost by $\mathbf{n}-1$. Labelling columns in this way, $\mathbf{iprm}\left[i\right]=j$ means that column $i-1$ of $A$ is in position $j$ in $A{P}_c$, where $P_{r}A{P}_c=LU$ expresses the factorization to be performed.

On exit: a new permutation is returned in the first $\mathbf{n}$ entries. The rest of the array contains data structures that will be used by other functions. The function computes the column elimination tree for $A$ and a post-order permutation on the tree. It then compounds the iprm permutation given or computed by the COLAMD algorthm with the post-order permutation. This array is needed by the $LU$ factorization function nag_superlu_lu_factorize (f11mec) and associated functions nag_superlu_solve_lu (f11mfc), nag_superlu_refine_lu (f11mhc) and nag_superlu_diagnostic_lu (f11mmc) and should be passed to them unchanged.

6:     fail – NagError *Input/Output

The NAG error argument (see Section 3.6 in the Essential Introduction).

6  Error Indicators and Warnings

NE_ALG_FAIL

COLAMD algorithm failed.

NE_ALLOC_FAIL

Dynamic memory allocation failed.

NE_BAD_PARAM

On entry, argument $⟨\mathit{\text{value}}⟩$ had an illegal value.

NE_INT

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

NE_INTERNAL_ERROR

An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.

NE_INVALID_PERM_COL

Incorrect column permutations in array iprm.

NE_SPARSE_COL

Incorrect specification of argument icolzp.

NE_SPARSE_ROW

Incorrect specification of argument irowix.

7  Accuracy

8  Parallelism and Performance

9  Further Comments

10  Example

10.1  Program Text

Program Text (f11mdce.c)

10.2  Program Data

Program Data (f11mdce.d)

10.3  Program Results

Program Results (f11mdce.r)