naginterfaces.library.sparse.real_​symm_​sort

naginterfaces.library.sparse.real_symm_sort(n, a, irow, icol, dup, zer)

real_symm_sort sorts the nonzero elements of a real sparse symmetric matrix, represented in symmetric coordinate storage format.

For full information please refer to the NAG Library document for f11zb

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f11/f11zbf.html

Parameters

nint

$n$, the order of the matrix $A$.

afloat, array-like, shape $\left(\text{nnz}\right)$

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

irowint, array-like, shape $\left(\text{nnz}\right)$

The row indices corresponding to the elements supplied in the array $a$.

icolint, array-like, shape $\left(\text{nnz}\right)$

The column indices corresponding to the elements supplied in the array $a$.

dupstr, length 1

Indicates how elements in $a$ with duplicate row and column indices are to be treated.

$dup=\text{'R'}$

Duplicate entries are removed, only the first entry is kept.

$dup=\text{'S'}$

The relevant values in $a$ are summed.

$dup=\text{'F'}$

The function fails with $errno$ = 3 on detecting a duplicate.

zerstr, length 1

Indicates how elements in $a$ with zero values are to be treated.

$zer=\text{'R'}$

The entries are removed.

$zer=\text{'K'}$

The entries are kept.

$zer=\text{'F'}$

The function fails with $errno$ = 4 on detecting a zero.

Returns

afloat, ndarray, shape $\left(\text{nnz}\right)$

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.

irowint, ndarray, shape $\left(\text{nnz}\right)$

The first $\text{nnz}$ elements contain the row indices corresponding to the elements returned in the array $a$.

icolint, ndarray, shape $\left(\text{nnz}\right)$

The first $\text{nnz}$ elements contain the column indices corresponding to the elements returned in the array $a$.

istrint, ndarray, shape $(n+1)$

$istr[\text{i}-1]-1$, for $\text{i}=1,2,\dots ,n$, is the starting address in the arrays $a$, $irow$ and $icol$ of row $i$ of the matrix $A$. $istr\left[n\right]-1$ is the address of the last element in $a$ plus one.

Raises

NagValueError

(errno $1$)

On entry, $zer=⟨value⟩$.

Constraint: $zer=\text{'R'}$, $\text{'K'}$ or $\text{'F'}$.

(errno $1$)

On entry, $dup=⟨value⟩$.

Constraint: $dup=\text{'R'}$, $\text{'S'}$ or $\text{'F'}$.

(errno $1$)

On entry, $\text{nnz}=⟨value⟩$.

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

(errno $1$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 1$.

(errno $2$)

On entry, $i=⟨value⟩$, $icol[i-1]=⟨value⟩$ and $irow[i-1]=⟨value⟩$.

Constraint: $icol[i-1]\ge 1$ and $icol[i-1]\le irow[i-1]$.

(errno $2$)

On entry, $i=⟨value⟩$, $irow[i-1]=⟨value⟩$ and $n=⟨value⟩$.

Constraint: $irow[i-1]\ge 1$ and $irow[i-1]\le n$.

(errno $3$)

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

(errno $4$)

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

Notes

real_symm_sort takes a symmetric coordinate storage (SCS) representation (see the F11 Introduction) of a real $n\times n$ sparse symmetric matrix $A$, and reorders the nonzero elements by increasing row index and increasing column index within each row. Entries with duplicate row and column indices may be removed. Alternatively, duplicate entries may be summed, which facilitates spare matrix addition (see Further Comments). Any entries with zero values may optionally be removed.

real_symm_sort also returns a pointer array $istr$ to the starting address of each row in $A$.