NAG Toolbox: nag_sparse_complex_herm_sort (f11zp)

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 lower triangular part of 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 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.

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{irow}\left(\mathit{i}\right)$, 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 lower triangular 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 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.

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 column 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 in the lower triangular part of $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{irow}\left(i\right)$,

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: f11zp_example

function f11zp_example


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

n = int64(4);
nz = int64(9);
irow = zeros(nz,1,'int64');
icol = zeros(nz,1,'int64');
a = zeros(nz,1);
a(1:nz)    = [ 1 + 2i;     0 + 0i;      0 + 3i;
               3 - 5i;     4 + 2i;      0 + 3i;
               2 + 4i;     1 - 1i;      1 + 3i];
irow(1:nz) = [ 3;          2;           3;
               4;          1;           2;
               3;          3;           3];
icol(1:nz) = [ 2;          1;           2;
               4;          1;           2;
               3;          2;           2];
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';
[nz, a, irow, icol, istr, ifail] = ...
  f11zp( ...
	 n, nz, a, irow, icol, dup, zero);

fprintf('\nNumber of elements in reordered sparse matrix: %5d\n',nz);
disp('New 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

f11zp example results

Number of elements in original sparse matrix:     9
Original matrix ordering:
   k      a(k)      i_k  j_k
   1  ( 1.0, 2.0)    3    2
   2  ( 0.0, 0.0)    2    1
   3  ( 0.0, 3.0)    3    2
   4  ( 3.0,-5.0)    4    4
   5  ( 4.0, 2.0)    1    1
   6  ( 0.0, 3.0)    2    2
   7  ( 2.0, 4.0)    3    3
   8  ( 1.0,-1.0)    3    2
   9  ( 1.0, 3.0)    3    2

Number of elements in reordered sparse matrix:     5
New ordering:
   k      a(k)      i_k  j_k
   1  ( 4.0, 2.0)    1    1
   2  ( 0.0, 3.0)    2    2
   3  ( 3.0, 7.0)    3    2
   4  ( 2.0, 4.0)    3    3
   5  ( 3.0,-5.0)    4    4