NAG Library Function Document

nag_sparse_sym_sort (f11zbc)

1

Purpose

2

Specification

3

Description

4

References

5

Arguments

1:    $\mathbf{n}$ – IntegerInput

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

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

2:    $\mathbf{nnz}$ – Integer *Input/Output

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

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

On exit: the number of lower triangular nonzero elements with unique row and column indices.

3:    $\mathbf{a}\left[\max \left(1,\mathbf{nnz}\right)\right]$ – doubleInput/Output

On entry: the nonzero elements of the lower triangular part of the matrix $A$. These may be in any order and there may be multiple nonzero elements with the same row and column indices.

On exit: the lower triangular nonzero elements ordered by increasing row index, and by increasing column index within each row. Each nonzero element has a unique row and column index.

4:    $\mathbf{irow}\left[\max \left(1,\mathbf{nnz}\right)\right]$ – IntegerInput/Output

On entry: the row indices of the elements supplied in array a.

Constraint: $1\le \mathbf{irow}\left[\mathit{i}\right]\le \mathbf{n}$, for $\mathit{i}=0,1,\dots ,\mathbf{nnz}-1$.

On exit: the first nnz elements contain the row indices corresponding to the elements returned in array a.

5:    $\mathbf{icol}\left[\max \left(1,\mathbf{nnz}\right)\right]$ – IntegerInput/Output

On entry: the column indices of the elements supplied in array a

Constraint: $1\le \mathbf{icol}\left[\mathit{i}\right]\le \mathbf{irow}\left[\mathit{i}\right]$, for $\mathit{i}=0,1,\dots ,\mathbf{nnz}-1$.

On exit: the first nnz elements contain the column indices corresponding to the elements returned in array a.

6:    $\mathbf{dup}$ – Nag_SparseSym_DupsInput

On entry: indicates how any nonzero elements with duplicate row and column indices are to be treated:

• if $\mathbf{dup}=\mathrm{Nag\_SparseSym\_RemoveDups}$ then duplicate elements are removed;
• if $\mathbf{dup}=\mathrm{Nag\_SparseSym\_SumDups}$ then duplicate elements are summed.

Constraint: $\mathbf{dup}=\mathrm{Nag\_SparseSym\_RemoveDups}$ or $\mathrm{Nag\_SparseSym\_SumDups}$.

7:    $\mathbf{zero}$ – Nag_SparseSym_ZerosInput

On entry: indicates how any elements with zero values in a are to be treated:

• if $\mathbf{zero}=\mathrm{Nag\_SparseSym\_RemoveZeros}$ then elements with zero value are removed;
• if $\mathbf{zero}=\mathrm{Nag\_SparseSym\_KeepZeros}$ then elements with zero value are kept.

Constraint: $\mathbf{zero}=\mathrm{Nag\_SparseSym\_RemoveZeros}$ or $\mathrm{Nag\_SparseSym\_KeepZeros}$.

8:    $\mathbf{istr}\left[\mathbf{n}+1\right]$ – IntegerOutput

On exit: $\mathbf{istr}\left[\mathit{i}-1\right]-1$, for $\mathit{i}=1,2,\dots ,\mathbf{n}$, is the starting index in the arrays a, irow and icol of each row $i$ of the matrix $A$. $\mathbf{istr}\left[n\right]-1$ is the index of the last nonzero element in $A$ plus one.

9:    $\mathbf{fail}$ – NagError *Input/Output

The NAG error argument (see Section 3.7 in How to Use the NAG Library and its Documentation).

6

Error Indicators and Warnings

NE_ALLOC_FAIL

Dynamic memory allocation failed.

NE_BAD_PARAM

On entry, argument dup had an illegal value.

On entry, argument zero had an illegal value.

NE_INT_ARG_LT

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

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

NE_SYMM_MATRIX

A nonzero element has been supplied which does not lie in the lower triangular part of the matrix $A$, i.e., one or more of the following constraints has been violated: $1\le \mathbf{irow}\left[\mathit{i}\right]\le \mathbf{n}$, $1\le \mathbf{icol}\left[\mathit{i}\right]\le \mathbf{irow}\left[\mathit{i}\right]$, for $\mathit{i}=0,1,\dots ,\mathbf{nnz}-1$.

7

Accuracy

8

Parallelism and Performance

9

Further Comments

10

Example

10.1

Program Text

Program Text (f11zbce.c)

10.2

Program Data

Program Data (f11zbce.d)

10.3

Program Results

Program Results (f11zbce.r)