f11 Chapter Contents
f11 Chapter Introduction
NAG C Library Manual

# NAG Library Function Documentnag_sparse_sym_matvec (f11xec)

## 1  Purpose

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

## 2  Specification

 #include #include
 void nag_sparse_sym_matvec (Integer n, Integer nnz, const double a[], const Integer irow[], const Integer icol[], Nag_SparseSym_CheckData check, const double x[], double y[], NagError *fail)

## 3  Description

nag_sparse_sym_matvec (f11xec) 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 Section 2.1.2 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_sym_matvec (f11xec) will be to compute the matrix-vector product required in the application of nag_sparse_sym_basic_solver (f11gec) to sparse symmetric linear systems. An illustration of this usage appears in nag_sparse_sym_precon_ssor_solve (f11jdc).

None.

## 5  Arguments

1:     nIntegerInput
On entry: $n$, the order of the matrix $A$.
Constraint: ${\mathbf{n}}\ge 1$.
2:     nnzIntegerInput
On entry: the number of nonzero elements in the lower triangular part of $A$.
Constraint: $1\le {\mathbf{nnz}}\le {\mathbf{n}}×\left({\mathbf{n}}+1\right)/2$.
3:     a[nnz]const doubleInput
On entry: 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_sym_sort (f11zbc) may be used to order the elements in this way.
4:     irow[nnz]const IntegerInput
5:     icol[nnz]const IntegerInput
On entry: 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_sym_sort (f11zbc)):
• $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}=0,1,\dots ,{\mathbf{nnz}}-1$;
• ${\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}=1,2,\dots ,{\mathbf{nnz}}-1$.
6:     checkNag_SparseSym_CheckDataInput
On entry: specifies whether or not the SCS representation of the matrix $A$, values of n, nnz, irow and icol should be checked.
${\mathbf{check}}=\mathrm{Nag_SparseSym_Check}$
Checks are carried out on the values of n, nnz, irow and icol.
${\mathbf{check}}=\mathrm{Nag_SparseSym_NoCheck}$
None of these checks are carried out.
Constraint: ${\mathbf{check}}=\mathrm{Nag_SparseSym_Check}$ or $\mathrm{Nag_SparseSym_NoCheck}$.
7:     x[n]const doubleInput
On entry: the vector $x$.
8:     y[n]doubleOutput
On exit: the vector $y$.
9:     failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

## 6  Error Indicators and Warnings

On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.
NE_INT
On entry, ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{n}}\ge 1$.
On entry, ${\mathbf{nnz}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{nnz}}\ge 1$.
NE_INT_2
On entry, ${\mathbf{nnz}}=〈\mathit{\text{value}}〉$ and ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{nnz}}\le {\mathbf{n}}×\left({\mathbf{n}}+1\right)/2$.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
NE_INVALID_SCS
On entry, $i=〈\mathit{\text{value}}〉$, ${\mathbf{icol}}\left[i-1\right]=〈\mathit{\text{value}}〉$, ${\mathbf{irow}}\left[i-1\right]=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{icol}}\left[i-1\right]\ge 1$ and ${\mathbf{icol}}\left[i-1\right]\le {\mathbf{irow}}\left[i-1\right]$.
On entry, $i=〈\mathit{\text{value}}〉$, ${\mathbf{irow}}\left[i-1\right]=〈\mathit{\text{value}}〉$, ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{irow}}\left[i-1\right]\ge 1$ and ${\mathbf{irow}}\left[i-1\right]\le {\mathbf{n}}$.
NE_NOT_STRICTLY_INCREASING
On entry, ${\mathbf{a}}\left[i-1\right]$ is out of order: $i=〈\mathit{\text{value}}〉$.
On entry, the location (${\mathbf{irow}}\left[i-1\right],{\mathbf{icol}}\left[i-1\right]$) is a duplicate: $i=〈\mathit{\text{value}}〉$. Consider calling nag_sparse_sym_sort (f11zbc) to reorder and sum or remove duplicates.

## 7  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.

### 8.1  Timing

The time taken for a call to nag_sparse_sym_matvec (f11xec) is proportional to nnz.

### 8.2  Use of check

It is expected that a common use of nag_sparse_sym_matvec (f11xec) will be to compute the matrix-vector product required in the application of nag_sparse_sym_basic_solver (f11gec) to sparse symmetric linear systems. In this situation nag_sparse_sym_matvec (f11xec) 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}}=\mathrm{Nag_SparseSym_Check}$ for the first of such calls, and to set ${\mathbf{check}}=\mathrm{Nag_SparseSym_NoCheck}$ for all subsequent calls.

## 9  Example

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

### 9.1  Program Text

Program Text (f11xece.c)

### 9.2  Program Data

Program Data (f11xece.d)

### 9.3  Program Results

Program Results (f11xece.r)