NAG CPP Interface
nagcpp::sparse::real_gen_matvec (f11xa)

1 Purpose

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=Ax, or the transposed matrix-vector product y=ATx, 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 real_gen_matvec will be to compute the matrix-vector product required in the application of f11bef (no CPP interface) to sparse linear systems. An illustration of this usage appears in Section 10 in real_​gen_​precon_​ssor_​solve (no CPP interface in the current release).

4 References

None.

5 Arguments

1: trans string Input
On entry: specifies whether or not the matrix A is transposed.
trans='N'
y=Ax is computed.
trans='T'
y=ATx is computed.
Constraint: trans='N' or '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)):
  • 1irow(i)n and 1icol(i)n, for i=0,1,,nnz-1;
  • irow(i-1)<irow(i) or irow(i-1)=irow(i) and icol(i-1)<icol(i), for i=1,2,,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)):
  • 1irow(i)n and 1icol(i)n, for i=0,1,,nnz-1;
  • irow(i-1)<irow(i) or irow(i-1)=irow(i) and icol(i-1)<icol(i), for i=1,2,,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:
checkstring
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.
See also Section 9.2.
Constraint: check='C' or 'N'.

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: nnzn2.
errorid=2
On entry, nnz = value.
Constraint: nnz1.
errorid=2
On entry, n = value.
Constraint: n1.
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]1 and icol[i-1]n.
errorid=3
On entry, i=value, irow[i-1]=value
and n = value.
Constraint: irow[i-1]1 and irow[i-1]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: 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 A. In the interests of both reliability and efficiency you are recommended to set check='C' for the first of such calls, and to set check='N' for all subsequent calls.

10 Example

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