NAG Library Function Document

nag_sparse_sym_sort (f11zbc)

1  Purpose

2  Specification

3  Description

4  References

5  Arguments

1:     n – IntegerInput

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

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

2:     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:     a[$\max \left(1,\mathbf{nnz}\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:     irow[$\max \left(1,\mathbf{nnz}\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:     icol[$\max \left(1,\mathbf{nnz}\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:     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:     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:     istr[$\mathbf{n}+1$] – 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:     fail – NagError *Input/Output

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

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)