NAG Toolbox: nag_sparse_complex_gen_sort (f11zn)

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)$ – complex 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 with $\mathbf{ifail}=\mathbf{3}$ on detecting a duplicate.

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

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

Indicates how any elements with zero values in array 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 with $\mathbf{ifail}=\mathbf{4}$ on detecting a zero.

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)$ – complex 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 $\text{'F'}$,
or	$\mathbf{zer}\ne \text{'R'}$, $\text{'K'}$ or $\text{'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 have 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: f11zn_example

function f11zn_example


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

n = int64(5);
nz = int64(15);
irow = zeros(nz,1,'int64');
icol = zeros(nz,1,'int64');
a = zeros(nz,1);

a(1:nz)    = [ 4 + 1i;  -2 + 6i;   1 - 3i;   -2 - 1i;   -3 + 0i;
               1 + 2i;   0 + 0i;   1 + 3i;   -1 - 1i;    6 - 3i;
               2 + 6i;   2 + 1i;   1 + 0i;    0 - 3i;    2 + 2i];
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  (%4.1f,%4.1f)%5d%5d\n', j, real(a(j)), imag(a(j)), ...
	  irow(j),icol(j));
end

% Sum duplicates and remove zeros
dup = 'S';
zero = 'R';
% Reorder along rows first (swap irow, icol to reorder by columns)
[nz, a, irow, icol, istr, ifail] = ...
  f11zn( ...
	 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  (%4.1f,%4.1f)%5d%5d\n', j, real(a(j)), imag(a(j)), ...
	  irow(j),icol(j));
end

f11zn example results

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