nag_sparse_real_symm_matvec (f11xe) computes a matrix-vector product involving a real sparse symmetric matrix stored in symmetric coordinate storage format.

Syntax

[y, ifail] = f11xe(a, irow, icol, check, x, 'n', n, 'nz', nz)

[y, ifail] = nag_sparse_real_symm_matvec(a, irow, icol, check, x, 'n', n, 'nz', nz)

Description

nag_sparse_real_symm_matvec (f11xe) computes the matrix-vector product

y = A x

where

A

is an

n

n

symmetric sparse matrix, of arbitrary sparsity pattern, stored in symmetric coordinate storage (SCS) format (see Symmetric coordinate storage (SCS) format in the F11 Chapter Introduction). The array a stores all nonzero elements in the lower triangular part 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_real_symm_matvec (f11xe) will be to compute the matrix-vector product required in the application of nag_sparse_real_symm_basic_solver (f11ge) to sparse symmetric linear systems. An illustration of this usage appears in nag_sparse_real_symm_precon_ssor_solve (f11jd).

References

None.

Parameters

Compulsory Input Parameters

1: $a (nz)$ – double array

The nonzero elements in the lower triangular part of 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_real_symm_sort (f11zb) may be used to order the elements in this way.

2: $irow (nz)$ – int64int32nag_int array

3: $icol (nz)$ – int64int32nag_int array

The row and column indices of the nonzero elements supplied in array a.

Constraints:

irow and icol must satisfy these constraints (which may be imposed by a call to nag_sparse_real_symm_sort (f11zb)):

$1 \leq irow (i) \leq n$ and $1 \leq icol (i) \leq irow (i)$ , for $i = 1, 2, \dots, nz$ ;
$irow (i - 1) < irow (i)$ or $irow (i - 1) = irow (i)$ and $icol (i - 1) < icol (i)$ , for $i = 2, 3, \dots, nz$ .

4: $check$ – string (length ≥ 1)

Specifies whether or not the SCS representation of the matrix

A

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

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

Optional Input Parameters

1: $n$ – int64int32nag_int scalar: Default: the dimension of the array x.
$n$ , the order of the matrix $A$ .

Constraint: $n \geq 1$ .
2: $nz$ – int64int32nag_int scalar: Default: the dimension of the arrays a, irow, icol. (An error is raised if these dimensions are not equal.)
The number of nonzero elements in the lower triangular part of $A$ .

Constraint: $1 \leq nz \leq n \times (n + 1) / 2$ .

Output Parameters

1: $y (n)$ – double array: The vector $y$ .
2: $ifail$ – int64int32nag_int scalar: $ifail = 0$ unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

Errors or warnings detected by the function:

$ifail = 1$

On entry,

check \neq'C'

'N'

$ifail = 2$

On entry,	$n < 1$ ,
or	$nz < 1$ ,
or	$nz > n \times (n + 1) / 2$ .

$ifail = 3$

On entry, the arrays irow and icol fail to satisfy the following constraints:

$1 \leq irow (i) \leq n$ and $1 \leq icol (i) \leq irow (i)$ , for $i = 1, 2, \dots, nz$ ;
$irow (i - 1) < irow (i)$ or $irow (i - 1) = irow (i)$ and $icol (i - 1) < icol (i)$ , for $i = 2, 3, \dots, nz$ .

Therefore a nonzero element has been supplied which does not lie in the lower triangular part of

A

, is out of order, or has duplicate row and column indices. Call nag_sparse_real_symm_sort (f11zb) to reorder and sum or remove duplicates.

$ifail = - 99$: An unexpected error has been triggered by this routine. Please contact NAG.

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

$ifail = - 999$: Dynamic memory allocation failed.

Accuracy

The computed vector

y

satisfies the error bound

{‖y - A x‖}_{\infty} \leq c (n) ε {‖A‖}_{\infty} {‖x‖}_{\infty},

where

c (n)

is a modest linear function of

n

, and

ε

is the machine precision.

Further Comments

Timing

The time taken for a call to nag_sparse_real_symm_matvec (f11xe) is proportional to nz.

Use of check

It is expected that a common use of nag_sparse_real_symm_matvec (f11xe) will be to compute the matrix-vector product required in the application of nag_sparse_real_symm_basic_solver (f11ge) to sparse symmetric linear systems. In this situation nag_sparse_real_symm_matvec (f11xe) 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.

Example

This example reads in a symmetric positive definite sparse matrix

A

and a vector

x

. It then calls nag_sparse_real_symm_matvec (f11xe) to compute the matrix-vector product

y = A x

Open in the MATLAB editor: f11xe_example

function f11xe_example


fprintf('f11xe example results\n\n');

% Sparse Matrix vector Product y=Ax, A is 9x9 symmetric. 

a     = [        4 -1 6 1 2 3 2 4 1 2 6 -4 1 -1 6 -1 -1 3 1 1 -1 1 4];
irow  = [int64(1) 2 2 3 3 4 5 5 6 6 6  7 7  7 7  8  8 8 9 9  9 9 9];
icol  = [int64(1) 1 2 2 3 4 1 5 3 4 6  2 5  6 7  4  6 8 1 5  6 8 9];

x     = [0.70  0.16  0.52  0.77  0.28  0.21  0.93  0.20  0.90];

check = 'C';
[y, ifail] = f11xe( ...
                    a, irow, icol, check, x);

disp('Matrix-vector product');
disp(y);

f11xe example results

Matrix-vector product
    4.1000
   -2.9400
    1.4100
    2.5300
    4.3500
    1.2900
    5.0100
    0.5200
    4.5700

PDF version (NAG web site, 64-bit version, 64-bit version)

Chapter Contents

Chapter Introduction

NAG Toolbox