NAG Library Function Document

nag_sparse_nsym_matvec (f11xac)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

+− 8 Further Comments

8.1 Timing

8.2 Use of check

+− 9 Example

9.1 Program Text

9.2 Program Data

9.3 Program Results

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 <nag.h>

#include <nagf11.h>

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 = 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

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

4 References

None.

5 Arguments

1: trans – Nag_TransTypeInput

On entry: specifies whether or not the matrix

A

is transposed.

$trans = Nag_NoTrans$: $y = A x$ is computed.
$trans = Nag_Trans$: $y = A^{T} x$ is computed.

Constraint:

trans = Nag_NoTrans

Nag_Trans

2: n – IntegerInput

On entry:

n

, the order of the matrix

A

Constraint:

n \geq 1

3: nnz – IntegerInput

On entry: the number of nonzero elements in the matrix

A

Constraint:

1 \leq nnz \leq 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 \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$ .

7: check – Nag_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.

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

6 Error Indicators and Warnings

NE_BAD_PARAM: On entry, argument $〈value〉$ had an illegal value.
NE_INT: On entry, $n = 〈value〉$ .
Constraint: $n \geq 1$ .; On entry, $nnz = 〈value〉$ .
Constraint: $nnz \geq 1$ .
NE_INT_2: On entry, $nnz = 〈value〉$ and $n = 〈value〉$ .
Constraint: $nnz \leq 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 = 〈value〉$ , $icol [i - 1] = 〈value〉$ , $n = 〈value〉$ .
Constraint: $icol [i - 1] \geq 1$ and $icol [i - 1] \leq n$ .; On entry, $i = 〈value〉$ , $irow [i - 1] = 〈value〉$ , $n = 〈value〉$ .
Constraint: $irow [i - 1] \geq 1$ and $irow [i - 1] \leq n$ .
NE_NOT_STRICTLY_INCREASING: On entry, $a [i - 1]$ is out of order: $i = 〈value〉$ .; On entry, the location ( $irow [i - 1], icol [i - 1]$ ) is a duplicate: $i = 〈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 - A x‖}_{\infty} \leq c (n) ε {‖A‖}_{\infty} {‖x‖}_{\infty}$ , if $trans = Nag_NoTrans$ , or
${‖y - A^{T} x‖}_{\infty} \leq c (n) ε {‖A^{T}‖}_{\infty} {‖x‖}_{\infty}$ , if $trans = Nag_Trans$ ,

where

c (n)

is a modest linear function of

n

, and

ε

is the machine precision.

8 Further Comments

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

check = Nag_SparseNsym_Check

for the first of such calls, and to set

check = 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 = A x

and the transposed matrix-vector product

y = A^{T} x

NAG Library Function Documentnag_sparse_nsym_matvec (f11xac)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

8.1 Timing

8.2 Use of check

9 Example

9.1 Program Text

9.2 Program Data

9.3 Program Results

NAG Library Function Document

nag_sparse_nsym_matvec (f11xac)