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

PDF version (NAG web site, 64-bit version, 64-bit version)
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, 'nnz', nnz)
[y, ifail] = nag_sparse_real_symm_matvec(a, irow, icol, check, x, 'n', n, 'nnz', nnz)

## Description

nag_sparse_real_symm_matvec (f11xe) computes the matrix-vector product
 y = Ax $y=Ax$
where A$A$ is an n$n$ by n$n$ symmetric sparse matrix, of arbitrary sparsity pattern, stored in symmetric coordinate storage (SCS) format (see Section [Symmetric coordinate storage (SCS) format] in the F11 Chapter Introduction). The array a stores all nonzero elements in the lower triangular part of A$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:     a(nnz) – double array
nnz, the dimension of the array, must satisfy the constraint 1nnzn × (n + 1) / 2$1\le {\mathbf{nnz}}\le {\mathbf{n}}×\left({\mathbf{n}}+1\right)/2$.
The nonzero elements in the lower triangular part of the matrix A$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:     irow(nnz) – int64int32nag_int array
3:     icol(nnz) – int64int32nag_int array
nnz, the dimension of the array, must satisfy the constraint 1nnzn × (n + 1) / 2$1\le {\mathbf{nnz}}\le {\mathbf{n}}×\left({\mathbf{n}}+1\right)/2$.
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)):
• 1irow(i)n$1\le {\mathbf{irow}}\left(\mathit{i}\right)\le {\mathbf{n}}$ and 1icol(i)irow(i)$1\le {\mathbf{icol}}\left(\mathit{i}\right)\le {\mathbf{irow}}\left(\mathit{i}\right)$, for i = 1,2,,nnz$\mathit{i}=1,2,\dots ,{\mathbf{nnz}}$;
• irow(i1) < irow(i)${\mathbf{irow}}\left(\mathit{i}-1\right)<{\mathbf{irow}}\left(\mathit{i}\right)$ or irow(i1) = irow(i)${\mathbf{irow}}\left(\mathit{i}-1\right)={\mathbf{irow}}\left(\mathit{i}\right)$ and icol(i1) < icol(i)${\mathbf{icol}}\left(\mathit{i}-1\right)<{\mathbf{icol}}\left(\mathit{i}\right)$, for i = 2,3,,nnz$\mathit{i}=2,3,\dots ,{\mathbf{nnz}}$.
4:     check – string (length ≥ 1)
Specifies whether or not the SCS representation of the matrix A$A$, values of n, nnz, irow and icol should be checked.
check = 'C'${\mathbf{check}}=\text{'C'}$
Checks are carried out on the values of n, nnz, irow and icol.
check = 'N'${\mathbf{check}}=\text{'N'}$
None of these checks are carried out.
Constraint: check = 'C'${\mathbf{check}}=\text{'C'}$ or 'N'$\text{'N'}$.
5:     x(n) – double array
n, the dimension of the array, must satisfy the constraint n1${\mathbf{n}}\ge 1$.
The vector x$x$.

### Optional Input Parameters

1:     n – int64int32nag_int scalar
Default: The dimension of the array x.
n$n$, the order of the matrix A$A$.
Constraint: n1${\mathbf{n}}\ge 1$.
2:     nnz – 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$A$.
Constraint: 1nnzn × (n + 1) / 2$1\le {\mathbf{nnz}}\le {\mathbf{n}}×\left({\mathbf{n}}+1\right)/2$.

None.

### Output Parameters

1:     y(n) – double array
The vector y$y$.
2:     ifail – int64int32nag_int scalar
${\mathrm{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:
ifail = 1${\mathbf{ifail}}=1$
 On entry, check ≠ 'C'${\mathbf{check}}\ne \text{'C'}$ or 'N'$\text{'N'}$.
ifail = 2${\mathbf{ifail}}=2$
 On entry, n < 1${\mathbf{n}}<1$, or nnz < 1${\mathbf{nnz}}<1$, or nnz > n × (n + 1) / 2${\mathbf{nnz}}>{\mathbf{n}}×\left({\mathbf{n}}+1\right)/2$.
ifail = 3${\mathbf{ifail}}=3$
On entry, the arrays irow and icol fail to satisfy the following constraints:
• 1irow(i)n$1\le {\mathbf{irow}}\left(i\right)\le {\mathbf{n}}$ and 1icol(i)irow(i)$1\le {\mathbf{icol}}\left(i\right)\le {\mathbf{irow}}\left(i\right)$, for i = 1,2,,nnz$i=1,2,\dots ,{\mathbf{nnz}}$;
• irow(i1) < irow(i)${\mathbf{irow}}\left(i-1\right)<{\mathbf{irow}}\left(i\right)$ or irow(i1) = irow(i)${\mathbf{irow}}\left(i-1\right)={\mathbf{irow}}\left(i\right)$ and icol(i1) < icol(i)${\mathbf{icol}}\left(i-1\right)<{\mathbf{icol}}\left(i\right)$, for i = 2,3,,nnz$i=2,3,\dots ,{\mathbf{nnz}}$.
Therefore a nonzero element has been supplied which does not lie in the lower triangular part of A$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.

## Accuracy

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

### Timing

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

### 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$A$. In the interests of both reliability and efficiency you are recommended to set check = 'C'${\mathbf{check}}=\text{'C'}$ for the first of such calls, and to set check = 'N'${\mathbf{check}}=\text{'N'}$ for all subsequent calls.

## Example

```function nag_sparse_real_symm_matvec_example
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];
check = 'C';
x = [0.7;
0.16;
0.52;
0.77;
0.28;
0.21;
0.93;
0.2;
0.9];
[y, ifail] = nag_sparse_real_symm_matvec(a, irow, icol, check, x)
```
```

y =

4.1000
-2.9400
1.4100
2.5300
4.3500
1.2900
5.0100
0.5200
4.5700

ifail =

0

```
```function f11xe_example
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];
check = 'C';
x = [0.7;
0.16;
0.52;
0.77;
0.28;
0.21;
0.93;
0.2;
0.9];
[y, ifail] = f11xe(a, irow, icol, check, x)
```
```

y =

4.1000
-2.9400
1.4100
2.5300
4.3500
1.2900
5.0100
0.5200
4.5700

ifail =

0

```

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2013