NAG Toolbox: nag_sparse_real_symm_sort (f11zb)

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)$ – double 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 real 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.

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

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.

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

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)$ – double 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'}$ or $\text{'S'}$.
or	$\mathbf{zer}\ne \text{'R'}$ or $\text{'K'}$.

   $\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 has 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}=-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: f11zb_example

function f11zb_example


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

n = int64(4);
nz = int64(9);
irow = zeros(nz,1,'int64');
icol = zeros(nz,1,'int64');

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

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

[nz, a, irow, icol, istr, ifail] = ...
f11zb( ...
       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%6.1f%5d%5d\n',j,a(j),irow(j),icol(j));
end

f11zb example results

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

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