Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_sparse_real_symm_matvec (f11xe)

## Purpose

nag_sparse_real_symm_matvec (f11xe) computes a matrix-vector product involving a real sparse symmetric matrix stored in symmetric coordinate storage format.

## Syntax

[y, ifail] = f11xe(a, irow, icol, check, x, 'n', n, 'nz', nz)
[y, ifail] = nag_sparse_real_symm_matvec(a, irow, icol, check, x, 'n', n, 'nz', nz)

## Description

nag_sparse_real_symm_matvec (f11xe) computes the matrix-vector product
 $y=Ax$
where $A$ is an $n$ by $n$ symmetric sparse matrix, of arbitrary sparsity pattern, stored in symmetric coordinate storage (SCS) format (see Symmetric coordinate storage (SCS) format in the F11 Chapter Introduction). The array a stores all nonzero elements in the lower triangular part of $A$, while arrays irow and icol store the corresponding row and column indices respectively.
It is envisaged that a common use of nag_sparse_real_symm_matvec (f11xe) will be to compute the matrix-vector product required in the application of nag_sparse_real_symm_basic_solver (f11ge) to sparse symmetric linear systems. An illustration of this usage appears in nag_sparse_real_symm_precon_ssor_solve (f11jd).

None.

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{a}\left({\mathbf{nz}}\right)$ – double array
The nonzero elements in the lower triangular part of the matrix $A$, ordered by increasing row index, and by increasing column index within each row. Multiple entries for the same row and column indices are not permitted. The function nag_sparse_real_symm_sort (f11zb) may be used to order the elements in this way.
2:     $\mathrm{irow}\left({\mathbf{nz}}\right)$int64int32nag_int array
3:     $\mathrm{icol}\left({\mathbf{nz}}\right)$int64int32nag_int array
The row and column indices of the nonzero elements supplied in array a.
Constraints:
irow and icol must satisfy these constraints (which may be imposed by a call to nag_sparse_real_symm_sort (f11zb)):
• $1\le {\mathbf{irow}}\left(\mathit{i}\right)\le {\mathbf{n}}$ and $1\le {\mathbf{icol}}\left(\mathit{i}\right)\le {\mathbf{irow}}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,{\mathbf{nz}}$;
• ${\mathbf{irow}}\left(\mathit{i}-1\right)<{\mathbf{irow}}\left(\mathit{i}\right)$ or ${\mathbf{irow}}\left(\mathit{i}-1\right)={\mathbf{irow}}\left(\mathit{i}\right)$ and ${\mathbf{icol}}\left(\mathit{i}-1\right)<{\mathbf{icol}}\left(\mathit{i}\right)$, for $\mathit{i}=2,3,\dots ,{\mathbf{nz}}$.
4:     $\mathrm{check}$ – string (length ≥ 1)
Specifies whether or not the SCS representation of the matrix $A$, values of n, nz, irow and icol should be checked.
${\mathbf{check}}=\text{'C'}$
Checks are carried out on the values of n, nz, irow and icol.
${\mathbf{check}}=\text{'N'}$
None of these checks are carried out.
Constraint: ${\mathbf{check}}=\text{'C'}$ or $\text{'N'}$.
5:     $\mathrm{x}\left({\mathbf{n}}\right)$ – double array
The vector $x$.

### Optional Input Parameters

1:     $\mathrm{n}$int64int32nag_int scalar
Default: the dimension of the array x.
$n$, the order of the matrix $A$.
Constraint: ${\mathbf{n}}\ge 1$.
2:     $\mathrm{nz}$int64int32nag_int scalar
Default: the dimension of the arrays a, irow, icol. (An error is raised if these dimensions are not equal.)
The number of nonzero elements in the lower triangular part of $A$.
Constraint: $1\le {\mathbf{nz}}\le {\mathbf{n}}×\left({\mathbf{n}}+1\right)/2$.

### Output Parameters

1:     $\mathrm{y}\left({\mathbf{n}}\right)$ – double array
The vector $y$.
2:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{ifail}}={\mathbf{0}}$ unless the function detects an error (see Error Indicators and Warnings).

## Error Indicators and Warnings

Errors or warnings detected by the function:
${\mathbf{ifail}}=1$
 On entry, ${\mathbf{check}}\ne \text{'C'}$ or $\text{'N'}$.
${\mathbf{ifail}}=2$
 On entry, ${\mathbf{n}}<1$, or ${\mathbf{nz}}<1$, or ${\mathbf{nz}}>{\mathbf{n}}×\left({\mathbf{n}}+1\right)/2$.
${\mathbf{ifail}}=3$
On entry, the arrays irow and icol fail to satisfy the following constraints:
• $1\le {\mathbf{irow}}\left(i\right)\le {\mathbf{n}}$ and $1\le {\mathbf{icol}}\left(i\right)\le {\mathbf{irow}}\left(i\right)$, for $i=1,2,\dots ,{\mathbf{nz}}$;
• ${\mathbf{irow}}\left(i-1\right)<{\mathbf{irow}}\left(i\right)$ or ${\mathbf{irow}}\left(i-1\right)={\mathbf{irow}}\left(i\right)$ and ${\mathbf{icol}}\left(i-1\right)<{\mathbf{icol}}\left(i\right)$, for $i=2,3,\dots ,{\mathbf{nz}}$.
Therefore a nonzero element has been supplied which does not lie in the lower triangular part of $A$, is out of order, or has duplicate row and column indices. Call nag_sparse_real_symm_sort (f11zb) to reorder and sum or remove duplicates.
${\mathbf{ifail}}=-99$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

## Accuracy

The computed vector $y$ satisfies the error bound
 $y-Ax∞≤cnεA∞x∞,$
where $c\left(n\right)$ is a modest linear function of $n$, and $\epsilon$ is the machine precision.

### Timing

The time taken for a call to nag_sparse_real_symm_matvec (f11xe) is proportional to nz.

### Use of check

It is expected that a common use of nag_sparse_real_symm_matvec (f11xe) will be to compute the matrix-vector product required in the application of nag_sparse_real_symm_basic_solver (f11ge) to sparse symmetric linear systems. In this situation nag_sparse_real_symm_matvec (f11xe) is likely to be called many times with the same matrix $A$. In the interests of both reliability and efficiency you are recommended to set ${\mathbf{check}}=\text{'C'}$ for the first of such calls, and to set ${\mathbf{check}}=\text{'N'}$ for all subsequent calls.

## Example

This example reads in a symmetric positive definite sparse matrix $A$ and a vector $x$. It then calls nag_sparse_real_symm_matvec (f11xe) to compute the matrix-vector product $y=Ax$.
```function f11xe_example

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

% Sparse Matrix vector Product y=Ax, A is 9x9 symmetric.

a     = [        4 -1 6 1 2 3 2 4 1 2 6 -4 1 -1 6 -1 -1 3 1 1 -1 1 4];
irow  = [int64(1) 2 2 3 3 4 5 5 6 6 6  7 7  7 7  8  8 8 9 9  9 9 9];
icol  = [int64(1) 1 2 2 3 4 1 5 3 4 6  2 5  6 7  4  6 8 1 5  6 8 9];

x     = [0.70  0.16  0.52  0.77  0.28  0.21  0.93  0.20  0.90];

check = 'C';
[y, ifail] = f11xe( ...
a, irow, icol, check, x);

disp('Matrix-vector product');
disp(y);

```
```f11xe example results

Matrix-vector product
4.1000
-2.9400
1.4100
2.5300
4.3500
1.2900
5.0100
0.5200
4.5700

```