NAG Toolbox: nag_sparse_real_gen_sort (f11za)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{n}$ – int64int32nag_int scalar

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

Constraint: $\mathbf{n}\ge 1$.

2:     $\mathrm{nz}$ – int64int32nag_int scalar

The number of nonzero elements in the matrix $A$.

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

3:     $\mathrm{a}\left(:\right)$ – double array

The dimension of the array a must be at least $\max \left(1,\mathbf{nz}\right)$

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.

4:     $\mathrm{irow}\left(:\right)$ – int64int32nag_int array

The dimension of the array irow must be at least $\max \left(1,\mathbf{nz}\right)$

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}=1,2,\dots ,\mathbf{nz}$.

5:     $\mathrm{icol}\left(:\right)$ – int64int32nag_int array

The dimension of the array icol must be at least $\max \left(1,\mathbf{nz}\right)$

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

Constraint: $1\le \mathbf{icol}\left(\mathit{i}\right)\le \mathbf{n}$, for $\mathit{i}=1,2,\dots ,\mathbf{nz}$.

6:     $\mathrm{dup}$ – string (length ≥ 1)

Indicates how any nonzero elements with duplicate row and column indices are to be treated.

$\mathbf{dup}=\text{'R'}$

The entries are removed.

$\mathbf{dup}=\text{'S'}$

The relevant values in a are summed.

$\mathbf{dup}=\text{'F'}$

The function fails on detecting a duplicate, with $\mathbf{ifail}=\mathbf{3}$.

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

7:     $\mathrm{zer}$ – string (length ≥ 1)

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

$\mathbf{zer}=\text{'R'}$

The entries are removed.

$\mathbf{zer}=\text{'K'}$

The entries are kept.

$\mathbf{zer}=\text{'F'}$

The function fails on detecting a zero, with $\mathbf{ifail}=\mathbf{4}$.

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

Optional Input Parameters

None.

Output Parameters

1:     $\mathrm{nz}$ – int64int32nag_int scalar

The number of nonzero elements with unique row and column indices.

2:     $\mathrm{a}\left(:\right)$ – double array

The dimension of the array a will be $\max \left(1,\mathbf{nz}\right)$

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.

3:     $\mathrm{irow}\left(:\right)$ – int64int32nag_int array

The dimension of the array irow will be $\max \left(1,\mathbf{nz}\right)$

The first nz elements contain the row indices corresponding to the nonzero elements returned in the array a.

4:     $\mathrm{icol}\left(:\right)$ – int64int32nag_int array

The dimension of the array icol will be $\max \left(1,\mathbf{nz}\right)$

The first nz elements contain the row indices corresponding to the nonzero elements returned in the array a.

5:     $\mathrm{istr}\left(\mathbf{n}+1\right)$ – int64int32nag_int array

$\mathbf{istr}\left(\mathit{i}\right)$, 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}+1\right)$ is the address of the last nonzero element in $A$ plus one.

6:     $\mathrm{ifail}$ – int64int32nag_int scalar

$\mathbf{ifail}=\mathbf{0}$ unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

   $\mathbf{ifail}=1$

On entry,	$\mathbf{n}<1$,
or	$\mathbf{nz}<0$,
or	$\mathbf{dup}\ne \text{'R'},\text{'S'}$, or 'F',
or	$\mathbf{zer}\ne \text{'R'},\text{'K'}$, or 'F'.

   $\mathbf{ifail}=2$

On entry, 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(i\right)\le \mathbf{n}$,
• $1\le \mathbf{icol}\left(i\right)\le \mathbf{n}$,

for $i=1,2,\dots ,\mathbf{nz}$

   $\mathbf{ifail}=3$

On entry, $\mathbf{dup}=\text{'F'}$ and nonzero elements have been supplied which have duplicate row and column indices.

   $\mathbf{ifail}=4$

On entry, $\mathbf{zer}=\text{'F'}$ and at least one matrix element has been supplied with a zero coefficient value.

   $\mathbf{ifail}=-99$

An unexpected error has been triggered by this routine. Please contact NAG.

   $\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

   $\mathbf{ifail}=-999$

Dynamic memory allocation failed.

Accuracy

Further Comments

Example

Open in the MATLAB editor: f11za_example

function f11za_example


fprintf('f11za example results\n\n');

% Sparse 5-by-5 matrix in coordinate storage form to be reordered 
n = int64(5);
nz = int64(15);
irow = zeros(nz,1,'int64');
icol = zeros(nz,1,'int64');
a(1:nz)     = [4; -2;  1; -2; -3;  1;  0;  1; -1;  6;  2;  2;  1;  1;  2];
irow(1:nz) = [3;  5;  4;  4;  5;  1;  1;  3;  2;  5;  1;  4;  2;  3;  4];
icol(1:nz) = [1;  2;  4;  2;  5;  2;  5;  5;  4;  5;  1;  2;  3;  3;  5];

fprintf('Number of elements in original sparse matrix: %5d\n',nz);
disp('Original matrix ordering:');
fprintf('   k   a(k)  i_k  j_k\n');
for j = 1:nz
  fprintf('%4d%6.1f%5d%5d\n',j,a(j),irow(j),icol(j));
end

% Sum duplicates and remove zeros
dup = 'S';
zero = 'R';

% Reorder along rows first (swap row, col to reorder by columns)
[nz, a, irow, icol, istr, ifail] = ...
f11za( ...
       n, nz, a, irow, icol, dup, zero);

fprintf('\nNumber of elements in reordered sparse matrix: %5d\n',nz);
disp('New ordering (by row first):');
fprintf('   k   a(k)  i_k  j_k\n');
for j = 1:nz
  fprintf('%4d%6.1f%5d%5d\n',j,a(j),irow(j),icol(j));
end

f11za example results

Number of elements in original sparse matrix:    15
Original matrix ordering:
   k   a(k)  i_k  j_k
   1   4.0    3    1
   2  -2.0    5    2
   3   1.0    4    4
   4  -2.0    4    2
   5  -3.0    5    5
   6   1.0    1    2
   7   0.0    1    5
   8   1.0    3    5
   9  -1.0    2    4
  10   6.0    5    5
  11   2.0    1    1
  12   2.0    4    2
  13   1.0    2    3
  14   1.0    3    3
  15   2.0    4    5

Number of elements in reordered sparse matrix:    11
New ordering (by row first):
   k   a(k)  i_k  j_k
   1   2.0    1    1
   2   1.0    1    2
   3   1.0    2    3
   4  -1.0    2    4
   5   4.0    3    1
   6   1.0    3    3
   7   1.0    3    5
   8   1.0    4    4
   9   2.0    4    5
  10  -2.0    5    2
  11   3.0    5    5