NAG Library Function Document

nag_sparse_nsym_sort (f11zac)

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

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

On exit: the number of 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 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:     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{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:     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:     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:     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_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  Further Comments

9  Example

9.1  Program Text

Program Text (f11zace.c)

9.2  Program Data

Program Data (f11zace.d)

9.3  Program Results

Program Results (f11zace.r)