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

2 Specification

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

3 Description

real_gen_matvec computes either the matrix-vector product

y = A x

, or the transposed matrix-vector product

y = A^{T} x

, according to the value of the argument trans, where

A

is an

n \times 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.

4 References

None.

5 Arguments

1: $trans$ – string Input

On entry: specifies whether or not the matrix

A

is transposed.

$trans ='N'$: $y = A x$ is computed.
$trans ='T'$: $y = A^{T} x$ is computed.

Constraint:

trans ='N'

'T'

2: $a (nnz)$ – 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: $irow (nnz)$ – 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 \leq irow (i) \leq n$ and $1 \leq icol (i) \leq n$ , for $i = 0, 1, \dots, nnz - 1$ ;
$irow (i - 1) < irow (i)$ or $irow (i - 1) = irow (i)$ and $icol (i - 1) < icol (i)$ , for $i = 1, 2, \dots, nnz - 1$ .

4: $icol (nnz)$ – 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 \leq irow (i) \leq n$ and $1 \leq icol (i) \leq n$ , for $i = 0, 1, \dots, nnz - 1$ ;
$irow (i - 1) < irow (i)$ or $irow (i - 1) = irow (i)$ and $icol (i - 1) < icol (i)$ , for $i = 1, 2, \dots, nnz - 1$ .

5: $x (n)$ – double array Input

On entry: the vector

x

6: $y (n)$ – double array Output

On exit: the vector

y

7: $opt$ – OptionalF11XA Input/Output

Optional parameter container, derived from Optional.

Container for:

check – string

This optional parameter may be set using the method OptionalF11XA::check and accessed via OptionalF11XA::get_check.

Default:

"N"

On entry: specifies whether or not the CS representation of the matrix

A

, values of n, nnz, irow and icol should be checked.

$check ='C'$: Checks are carried on the values of n, nnz, irow and icol.
$check ='N'$: None of these checks are carried out.

5.1Additional Quantities

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

6 Exceptions 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

$errorid = 1$: On entry, $trans = ⟨ value ⟩$ .
Constraint: $trans = "N" or "T"$ .

$errorid = 1$: On entry, $check = ⟨ value ⟩$ .
Constraint: $check = "C" or "N"$ .

$errorid = 2$: On entry, $nnz = ⟨ value ⟩$ and $n = ⟨ value ⟩$ .
Constraint: $nnz \leq n^{2}$ .

$errorid = 2$: On entry, $nnz = ⟨ value ⟩$ .
Constraint: $nnz \geq 1$ .

$errorid = 2$: On entry, $n = ⟨ value ⟩$ .
Constraint: $n \geq 1$ .

$errorid = 3$: On entry, the location ( $irow [I - 1], icol [I - 1]$ ) is a duplicate:
$I = ⟨ value ⟩$ .

$errorid = 3$: On entry, $a [i - 1]$ is out of order:
$i = ⟨ value ⟩$ .

$errorid = 3$: On entry, $i = ⟨ value ⟩$ , $icol [i - 1] = ⟨ value ⟩$
and $n = ⟨ value ⟩$ .
Constraint: $icol [i - 1] \geq 1$ and $icol [i - 1] \leq n$ .

$errorid = 3$: On entry, $i = ⟨ value ⟩$ , $irow [i - 1] = ⟨ value ⟩$
and $n = ⟨ value ⟩$ .
Constraint: $irow [i - 1] \geq 1$ and $irow [i - 1] \leq n$ .

$errorid = 10601$: On entry, argument $⟨ value ⟩$ must be a vector of size $⟨ value ⟩$ array.
Supplied argument has $⟨ value ⟩$ dimensions.

$errorid = 10601$: On entry, argument $⟨ value ⟩$ must be a vector of size $⟨ value ⟩$ array.
Supplied argument was a vector of size $⟨ value ⟩$ .

$errorid = 10601$: On entry, argument $⟨ value ⟩$ must be a vector of size $⟨ value ⟩$ array.
The size for the supplied array could not be ascertained.

$errorid = 10602$: On entry, the raw data component of $⟨ value ⟩$ is null.

$errorid = 10603$: On entry, unable to ascertain a value for $⟨ value ⟩$ .

$errorid = −99$: An unexpected error has been triggered by this routine.

$errorid = −399$: Your licence key may have expired or may not have been installed correctly.

$errorid = −999$: Dynamic memory allocation failed.

7 Accuracy

The computed vector

y

satisfies the error bound:

${‖ y - A x ‖}_{\infty} \leq c (n) ε {‖ A ‖}_{\infty} {‖ x ‖}_{\infty}$ , if $trans ='N'$ , or
${‖ y - A^{T} x ‖}_{\infty} \leq c (n) ε {‖ A^{T} ‖}_{\infty} {‖ x ‖}_{\infty}$ , if $trans ='T'$ ,

where

c (n)

is a modest linear function of

n

, and

ε

is the machine precision.

8 Parallelism and Performance

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

9 Further Comments

9.1 Timing

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

9.2 Use 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