# NAG CPP Interfacenagcpp::sparse::real_gen_matvec (f11xa)

Settings help

CPP Name Style:

## 1Purpose

real_gen_matvec computes a matrix-vector or transposed matrix-vector product involving a real sparse nonsymmetric matrix stored in coordinate storage format.

## 2Specification

```#include "f11/nagcpp_f11xa.hpp"
```
```template <typename A, typename IROW, typename ICOL, typename X, typename Y>

void function real_gen_matvec(const string trans, const A &a, const IROW &irow, const ICOL &icol, const X &x, Y &&y, OptionalF11XA opt)```
```template <typename A, typename IROW, typename ICOL, typename X, typename Y>

void function real_gen_matvec(const string trans, const A &a, const IROW &irow, const ICOL &icol, const X &x, Y &&y)```

## 3Description

real_gen_matvec 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×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 real_gen_matvec will be to compute the matrix-vector product required in the application of f11bef (no CPP interface) to sparse linear systems.
None.

## 5Arguments

1: $\mathbf{trans}$string Input
On entry: specifies whether or not the matrix $A$ is transposed.
${\mathbf{trans}}=\text{'N'}$
$y=Ax$ is computed.
${\mathbf{trans}}=\text{'T'}$
$y={A}^{\mathrm{T}}x$ is computed.
Constraint: ${\mathbf{trans}}=\text{'N'}$ or $\text{'T'}$.
2: $\mathbf{a}\left({\mathbf{nnz}}\right)$double array Input
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 rtnrefs1 (no CPP interface) may be used to order the elements in this way.
3: $\mathbf{irow}\left({\mathbf{nnz}}\right)$types::f77_integer array Input
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 rtnrefs1 (no CPP interface)):
• $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$.
4: $\mathbf{icol}\left({\mathbf{nnz}}\right)$types::f77_integer array Input
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 rtnrefs1 (no CPP interface)):
• $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$.
5: $\mathbf{x}\left({\mathbf{n}}\right)$double array Input
On entry: the vector $x$.
6: $\mathbf{y}\left({\mathbf{n}}\right)$double array Output
On exit: the vector $y$.
7: $\mathbf{opt}$OptionalF11XA Input/Output
Optional parameter container, derived from Optional.
Container for:
checkstring
This optional parameter may be set using the method OptionalF11XA::check and accessed via OptionalF11XA::get_check.
Default: $\text{"N"}$
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}}=\text{'C'}$
Checks are carried on the values of n, nnz, irow and icol.
${\mathbf{check}}=\text{'N'}$
None of these checks are carried out.
See also Section 9.2.
Constraint: ${\mathbf{check}}=\text{'C'}$ or $\text{'N'}$.

### 5.1Additional Quantities

1: $\mathbf{n}$
$n$, the order of the matrix $A$
2: $\mathbf{nnz}$
The number of nonzero elements in the matrix $A$

## 6Exceptions and Warnings

Errors or warnings detected by the function:
All errors and warnings have an associated numeric error code field, errorid, stored either as a member of the thrown exception object (see errorid), or as a member of opt.ifail, depending on how errors and warnings are being handled (see Error Handling for more details).
Raises: ErrorException
$\mathbf{errorid}=1$
On entry, ${\mathbf{trans}}=⟨\mathit{value}⟩$.
Constraint: ${\mathbf{trans}}=\text{"N"}\text{​ or ​}\text{"T"}$.
$\mathbf{errorid}=1$
On entry, ${\mathbf{check}}=⟨\mathit{value}⟩$.
Constraint: ${\mathbf{check}}=\text{"C"}\text{​ or ​}\text{"N"}$.
$\mathbf{errorid}=2$
On entry, ${\mathbf{nnz}}=⟨\mathit{value}⟩$ and ${\mathbf{n}}=⟨\mathit{value}⟩$.
Constraint: ${\mathbf{nnz}}\le {{\mathbf{n}}}^{2}$.
$\mathbf{errorid}=2$
On entry, ${\mathbf{nnz}}=⟨\mathit{value}⟩$.
Constraint: ${\mathbf{nnz}}\ge 1$.
$\mathbf{errorid}=2$
On entry, ${\mathbf{n}}=⟨\mathit{value}⟩$.
Constraint: ${\mathbf{n}}\ge 1$.
$\mathbf{errorid}=3$
On entry, the location (${\mathbf{irow}}\left[I-1\right],{\mathbf{icol}}\left[I-1\right]$) is a duplicate:
$I=⟨\mathit{value}⟩$.
$\mathbf{errorid}=3$
On entry, ${\mathbf{a}}\left[i-1\right]$ is out of order:
$i=⟨\mathit{value}⟩$.
$\mathbf{errorid}=3$
On entry, $i=⟨\mathit{value}⟩$, ${\mathbf{icol}}\left[i-1\right]=⟨\mathit{value}⟩$
and ${\mathbf{n}}=⟨\mathit{value}⟩$.
Constraint: ${\mathbf{icol}}\left[i-1\right]\ge 1$ and ${\mathbf{icol}}\left[i-1\right]\le {\mathbf{n}}$.
$\mathbf{errorid}=3$
On entry, $i=⟨\mathit{value}⟩$, ${\mathbf{irow}}\left[i-1\right]=⟨\mathit{value}⟩$
and ${\mathbf{n}}=⟨\mathit{value}⟩$.
Constraint: ${\mathbf{irow}}\left[i-1\right]\ge 1$ and ${\mathbf{irow}}\left[i-1\right]\le {\mathbf{n}}$.
$\mathbf{errorid}=10601$
On entry, argument $⟨\mathit{\text{value}}⟩$ must be a vector of size $⟨\mathit{\text{value}}⟩$ array.
Supplied argument has $⟨\mathit{\text{value}}⟩$ dimensions.
$\mathbf{errorid}=10601$
On entry, argument $⟨\mathit{\text{value}}⟩$ must be a vector of size $⟨\mathit{\text{value}}⟩$ array.
Supplied argument was a vector of size $⟨\mathit{\text{value}}⟩$.
$\mathbf{errorid}=10601$
On entry, argument $⟨\mathit{\text{value}}⟩$ must be a vector of size $⟨\mathit{\text{value}}⟩$ array.
The size for the supplied array could not be ascertained.
$\mathbf{errorid}=10602$
On entry, the raw data component of $⟨\mathit{\text{value}}⟩$ is null.
$\mathbf{errorid}=10603$
On entry, unable to ascertain a value for $⟨\mathit{\text{value}}⟩$.
$\mathbf{errorid}=-99$
An unexpected error has been triggered by this routine.
$\mathbf{errorid}=-399$
Your licence key may have expired or may not have been installed correctly.
$\mathbf{errorid}=-999$
Dynamic memory allocation failed.

## 7Accuracy

The computed vector $y$ satisfies the error bound:
• ${‖y-Ax‖}_{\infty }\le c\left(n\right)\epsilon {‖A‖}_{\infty }{‖x‖}_{\infty }$, if ${\mathbf{trans}}=\text{'N'}$, or
• ${‖y-{A}^{\mathrm{T}}x‖}_{\infty }\le c\left(n\right)\epsilon {‖{A}^{\mathrm{T}}‖}_{\infty }{‖x‖}_{\infty }$, if ${\mathbf{trans}}=\text{'T'}$,
where $c\left(n\right)$ is a modest linear function of $n$, and $\epsilon$ is the machine precision.

## 8Parallelism and Performance

Please see the description for the underlying computational routine in this section of the FL Interface documentation.

## 9Further Comments

### 9.1Timing

The time taken for a call to real_gen_matvec is proportional to nnz.

### 9.2Use of check

It is expected that a common use of real_gen_matvec will be to compute the matrix-vector product required in the application of f11bef (no CPP interface) to sparse linear systems. In this situation real_gen_matvec 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.

## 10Example

Examples of the use of this method may be found in the examples for: real_​nmf_​rcomm.