NAG Library Function Document

nag_sparse_nsym_sort (f11zac)

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 matrix $A$.

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

On exit: the number of 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 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 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{n}$, 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_SparseNsym_DupsInput

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

• if $\mathbf{dup}=\mathrm{Nag\_SparseNsym\_RemoveDups}$ then duplicate elements are removed;
• if $\mathbf{dup}=\mathrm{Nag\_SparseNsym\_SumDups}$ then the relevant values in array a are summed;
• if $\mathbf{dup}=\mathrm{Nag\_SparseNsym\_FailDups}$ then the function fails on detecting a duplicate.

Constraint: $\mathbf{dup}=\mathrm{Nag\_SparseNsym\_RemoveDups}$, $\mathrm{Nag\_SparseNsym\_SumDups}$ or $\mathrm{Nag\_SparseNsym\_FailDups}$.

7:    $\mathbf{zero}$ – Nag_SparseNsym_ZerosInput

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

• if $\mathbf{zero}=\mathrm{Nag\_SparseNsym\_RemoveZeros}$ then the entries are removed;
• if $\mathbf{zero}=\mathrm{Nag\_SparseNsym\_KeepZeros}$ then the entries are kept;
• if $\mathbf{zero}=\mathrm{Nag\_SparseNsym\_FailZeros}$ then the function fails on detecting a zero.

Constraint: $\mathbf{zero}=\mathrm{Nag\_SparseNsym\_RemoveZeros}$, $\mathrm{Nag\_SparseNsym\_KeepZeros}$ or $\mathrm{Nag\_SparseNsym\_FailZeros}$.

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]$ contains the number of nonzero elements 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_NON_ZERO_DUP

Nonzero elements have been supplied which have duplicate row and column indices, when $\mathbf{dup}=\mathrm{Nag\_SparseNsym\_FailDups}$.

NE_NONSYMM_MATRIX

A nonzero element has been supplied which does not lie within 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{n}$, for $\mathit{i}=0,1,\dots ,\mathbf{nnz}-1$.

NE_ZERO_COEFF

At least one matrix element has been supplied with a zero coefficient value, when $\mathbf{zero}=\mathrm{Nag\_SparseNsym\_FailZeros}$.

7

Accuracy

8

Parallelism and Performance

9

Further Comments

10

Example

10.1

Program Text

Program Text (f11zace.c)

10.2

Program Data

Program Data (f11zace.d)

10.3

Program Results

Program Results (f11zace.r)