NAG Library Function Document

nag_sparse_herm_sort (f11zpc)

1  Purpose

2  Specification

3  Description

4  References

5  Arguments

1:     n – IntegerInput

On entry: $n$, 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[$\mathit{dim}$] – ComplexInput/Output

Note: the dimension, dim, of the array a must be at least $\max \left(1,\mathbf{nnz}\right)$.

On entry: the nonzero elements of the lower triangular part of the complex 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[$\mathit{dim}$] – IntegerInput/Output

Note: the dimension, dim, of the array irow must be at least $\max \left(1,\mathbf{nnz}\right)$.

On entry: the row indices corresponding to the nonzero elements supplied in the 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 nonzero elements returned in the array a.

5:     icol[$\mathit{dim}$] – IntegerInput/Output

Note: the dimension, dim, of the array icol must be at least $\max \left(1,\mathbf{nnz}\right)$.

On entry: the column indices corresponding to the nonzero elements supplied in the 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 nonzero elements returned in the array a.

6:     dup – Nag_SparseSym_DupsInput

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

$\mathbf{dup}=\mathrm{Nag\_SparseSym\_RemoveDups}$

The entries are removed.

$\mathbf{dup}=\mathrm{Nag\_SparseSym\_SumDups}$

The relevant values in a are summed.

$\mathbf{dup}=\mathrm{Nag\_SparseSym\_FailDups}$

The function fails with $\mathbf{fail}\mathbf{.}\mathbf{code}=$ NE_NON_ZERO_DUP on detecting a duplicate.

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

7:     zero – Nag_SparseSym_ZerosInput

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

$\mathbf{zero}=\mathrm{Nag\_SparseSym\_RemoveZeros}$

The entries are removed.

$\mathbf{zero}=\mathrm{Nag\_SparseSym\_KeepZeros}$

The entries are kept.

$\mathbf{zero}=\mathrm{Nag\_SparseSym\_FailZeros}$

The function fails with $\mathbf{fail}\mathbf{.}\mathbf{code}=$ NE_ZERO_COEFF on detecting a zero.

Constraint: $\mathbf{zero}=\mathrm{Nag\_SparseSym\_RemoveZeros}$, $\mathrm{Nag\_SparseSym\_KeepZeros}$ or $\mathrm{Nag\_SparseSym\_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 address in the arrays a, irow and icol of row $i$ of the matrix $A$. $\mathbf{istr}\left[\mathbf{n}\right]-1$ is the address 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 $⟨\mathit{\text{value}}⟩$ had an illegal value.

NE_INT

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_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_SCS

On entry, $\mathit{I}=⟨\mathit{\text{value}}⟩$, $\mathbf{icol}\left[\mathit{I}-1\right]=⟨\mathit{\text{value}}⟩$ and $\mathbf{irow}\left[\mathit{I}-1\right]=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{icol}\left[\mathit{I}-1\right]\ge 1$ and $\mathbf{icol}\left[\mathit{I}-1\right]\le \mathbf{irow}\left[\mathit{I}-1\right]$.

On entry, $i=⟨\mathit{\text{value}}⟩$, $\mathbf{irow}\left[i-1\right]=⟨\mathit{\text{value}}⟩$ and $\mathbf{n}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{irow}\left[i-1\right]\ge 1$ and $\mathbf{irow}\left[i-1\right]\le \mathbf{n}$.

NE_NON_ZERO_DUP

On entry, a duplicate entry has been found in row $\mathit{I}$ and column $\mathit{J}$: $\mathit{I}=⟨\mathit{\text{value}}⟩$, $\mathit{J}=⟨\mathit{\text{value}}⟩$.

NE_ZERO_COEFF

On entry, a zero entry has been found in row $\mathit{I}$ and column $\mathit{J}$: $\mathit{I}=⟨\mathit{\text{value}}⟩$, $\mathit{J}=⟨\mathit{\text{value}}⟩$.

7  Accuracy

8  Parallelism and Performance

9  Further Comments

10  Example

10.1  Program Text

Program Text (f11zpce.c)

10.2  Program Data

Program Data (f11zpce.d)

10.3  Program Results

Program Results (f11zpce.r)