naginterfaces.library.sparse.real_​rect_​sort

naginterfaces.library.sparse.real_rect_sort(m, a, irow, n=None, icol=None, istc=None, dup='S', zer='R')

real_rect_sort sorts the nonzero elements of a real sparse rectangular matrix, represented in coordinate storage or compressed column storage format.

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

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

Parameters

mint

$m$, the number of rows in the matrix $A$.

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

The nonzero elements of the matrix $A$. If column indices are supplied via $icol$, the elements may be in any order. If column starting addresses are supplied via $istc$, the elements must be ordered by increasing column index. 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$.

nNone or int, optional

$n$, the number of columns in the matrix $A$.

If you are providing column starting addresses via $istc$ then your supplied value of $n$ will be ignored and it will be inferred from that array instead.

icolNone or int, array-like, shape $\left(\text{nnz}\right)$, optional

Must be used to supply the column indices corresponding to the elements supplied in the array $a$, when $a$ is represented in coordinate storage format.

istcNone or int, array-like, shape $(n+1)$, optional

Must be used to supply the starting address of each column, as supplied in the array $a$, when $a$ is represented in compressed column storage format.

dupstr, length 1, optional

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$ = 12 on detecting a duplicate.

zerstr, length 1, optional

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$ = 13 on detecting a zero.

Returns

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

The nonzero elements ordered by increasing column index, and by increasing row index within each column. Each nonzero element has a unique row and column index.

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

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

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

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

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

The starting address of each column, as returned in the array $a$. $istc\left[n\right]-1$ is the address of the last element in $a$ plus one.

Raises

NagValueError

(errno $1$)

On entry, $m=⟨value⟩$.

Constraint: $m\ge 1$.

(errno $2$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 1$.

(errno $3$)

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

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

(errno $5$)

On entry, $dup=⟨value⟩$.

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

(errno $6$)

On entry, $zer=⟨value⟩$.

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

(errno $7$)

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

Constraint: $1\le irow[i-1]\le m$.

(errno $8$)

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

Constraint: if column indices are supplied, then $1\le icol[i-1]\le n$.

(errno $9$)

On entry, $istc\left[0\right]=⟨value⟩$.

Constraint: $istc\left[0\right]=1$.

(errno $10$)

On entry, $i=⟨value⟩$, $istc[\text{i}-1]=⟨value⟩$ and $istc\left[\text{i}\right]=⟨value⟩$.

Constraint: $istc[\text{i}-1]\le istc\left[\text{i}\right]$, for $\text{i}=1,2,\dots ,n$

(errno $11$)

On entry, $n=⟨value⟩$, $istc\left[n\right]=⟨value⟩$ and $\text{nnz}=⟨value⟩$.

Constraint: $istc\left[n\right]=\text{nnz}+1$.

(errno $12$)

On entry, a duplicate entry has been found in row $⟨value⟩$ and column $⟨value⟩$.

(errno $13$)

On entry, a zero entry has been found in row $⟨value⟩$ and column $⟨value⟩$.

(errno $14$)

Exactly one of $icol$ and $istc$ must be provided.

(errno $15$)

$n$ or $istc$ must be provided.

Notes

real_rect_sort takes a coordinate storage (CS) representation (see the F11 Introduction), or compressed column storage (CCS) representation (see the F11 Introduction) of a real $m\times n$ sparse rectangular matrix $A$, and reorders the nonzero elements by increasing column index and increasing row index within each column.

Entries with duplicate row and column indices may be removed. Alternatively, duplicate entries may be summed, which facilitates sparse matrix addition (see Further Comments). Any entries with zero values may optionally be removed.

Both CS and CCS representations of the resulting matrix are output, which allows real_rect_sort to be used to convert between the two formats (see Further Comments).