f11 Chapter Contents
f11 Chapter Introduction
NAG C Library Manual

# NAG Library Function Documentnag_sparse_nsym_matvec (f11xac)

## 1  Purpose

nag_sparse_nsym_matvec (f11xac) computes a matrix-vector or transposed matrix-vector product involving a real sparse nonsymmetric matrix stored in coordinate storage format.

## 2  Specification

 #include #include
 void nag_sparse_nsym_matvec (Nag_TransType trans, Integer n, Integer nnz, const double a[], const Integer irow[], const Integer icol[], Nag_SparseNsym_CheckData check, const double x[], double y[], NagError *fail)

## 3  Description

nag_sparse_nsym_matvec (f11xac) computes either the matrix-vector product $y=Ax$, or the transposed matrix-vector product $y={A}^{\mathrm{T}}x$, according to the value of the argument trans, where $A$ is an $n$ by $n$ sparse nonsymmetric matrix, of arbitrary sparsity pattern. The matrix $A$ is stored in coordinate storage (CS) format (see Section 2.1.1 in the f11 Chapter Introduction). The array a stores all nonzero elements 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_nsym_matvec (f11xac) will be to compute the matrix-vector product required in the application of nag_sparse_nsym_basic_solver (f11bec) to sparse linear systems. An illustration of this usage appears in Section 9 in nag_sparse_nsym_precon_ssor_solve (f11ddc).

None.

## 5  Arguments

1:     transNag_TransTypeInput
On entry: specifies whether or not the matrix $A$ is transposed.
${\mathbf{trans}}=\mathrm{Nag_NoTrans}$
$y=Ax$ is computed.
${\mathbf{trans}}=\mathrm{Nag_Trans}$
$y={A}^{\mathrm{T}}x$ is computed.
Constraint: ${\mathbf{trans}}=\mathrm{Nag_NoTrans}$ or $\mathrm{Nag_Trans}$.
2:     nIntegerInput
On entry: $n$, the order of the matrix $A$.
Constraint: ${\mathbf{n}}\ge 1$.
3:     nnzIntegerInput
On entry: the number of nonzero elements in the matrix $A$.
Constraint: $1\le {\mathbf{nnz}}\le {{\mathbf{n}}}^{2}$.
4:     a[nnz]const doubleInput
On entry: the nonzero elements in 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_nsym_sort (f11zac) may be used to order the elements in this way.
5:     irow[nnz]const IntegerInput
6:     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 the following constraints (which may be imposed by a call to nag_sparse_nsym_sort (f11zac)):
• $1\le {\mathbf{irow}}\left[\mathit{i}\right]\le {\mathbf{n}}$ and $1\le {\mathbf{icol}}\left[\mathit{i}\right]\le {\mathbf{n}}$, 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$.
7:     checkNag_SparseNsym_CheckDataInput
On entry: specifies whether or not the CS representation of the matrix $A$, values of n, nnz, irow and icol should be checked.
${\mathbf{check}}=\mathrm{Nag_SparseNsym_Check}$
Checks are carried on the values of n, nnz, irow and icol.
${\mathbf{check}}=\mathrm{Nag_SparseNsym_NoCheck}$
None of these checks are carried out.
Constraint: ${\mathbf{check}}=\mathrm{Nag_SparseNsym_Check}$ or $\mathrm{Nag_SparseNsym_NoCheck}$.
8:     x[n]const doubleInput
On entry: the vector $x$.
9:     y[n]doubleOutput
On exit: the vector $y$.
10:   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}}}^{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_CS
On entry, $i=〈\mathit{\text{value}}〉$, ${\mathbf{icol}}\left[i-1\right]=〈\mathit{\text{value}}〉$, ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{icol}}\left[i-1\right]\ge 1$ and ${\mathbf{icol}}\left[i-1\right]\le {\mathbf{n}}$.
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_nsym_sort (f11zac) to reorder and sum or remove duplicates.

## 7  Accuracy

The computed vector $y$ satisfies the error bound:
• ${‖y-Ax‖}_{\infty }\le c\left(n\right)\epsilon {‖A‖}_{\infty }{‖x‖}_{\infty }$, if ${\mathbf{trans}}=\mathrm{Nag_NoTrans}$, or
• ${‖y-{A}^{\mathrm{T}}x‖}_{\infty }\le c\left(n\right)\epsilon {‖{A}^{\mathrm{T}}‖}_{\infty }{‖x‖}_{\infty }$, if ${\mathbf{trans}}=\mathrm{Nag_Trans}$,
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_nsym_matvec (f11xac) is proportional to nnz.

### 8.2  Use of check

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

## 9  Example

This example reads in a sparse matrix $A$ and a vector $x$. It then calls nag_sparse_nsym_matvec (f11xac) to compute the matrix-vector product $y=Ax$ and the transposed matrix-vector product $y={A}^{\mathrm{T}}x$.

### 9.1  Program Text

Program Text (f11xace.c)

### 9.2  Program Data

Program Data (f11xace.d)

### 9.3  Program Results

Program Results (f11xace.r)