nag_sparse_complex_gen_matvec (f11xn) computes a matrix-vector or conjugate transposed matrix-vector product involving a complex sparse non-Hermitian matrix stored in coordinate storage format.

Syntax

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

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

Description

nag_sparse_complex_gen_matvec (f11xn) computes either the matrix-vector product

y = A x

, or the conjugate transposed matrix-vector product

y = A^{H} x

, according to the value of the argument trans, where

A

is a complex

n

n

sparse non-Hermitian matrix, of arbitrary sparsity pattern. The matrix

A

is stored in coordinate storage (CS) format (see Coordinate storage (CS) format in the F11 Chapter Introduction). The array a stores all the 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_complex_gen_matvec (f11xn) will be to compute the matrix-vector product required in the application of nag_sparse_complex_gen_basic_solver (f11bs) to sparse complex linear systems. This is illustrated in Example in nag_sparse_complex_gen_precon_ssor_solve (f11dr).

References

None.

Parameters

Compulsory Input Parameters

1: $trans$ – string (length ≥ 1)

Specifies whether or not the matrix

A

is conjugate transposed.

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

Constraint:

trans ='N'

'T'

2: $a (nz)$ – complex array

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_complex_gen_sort (f11zn) may be used to order the elements in this way.

3: $irow (nz)$ – int64int32nag_int array

4: $icol (nz)$ – int64int32nag_int array

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

Constraints:

$1 \leq irow (i) \leq n$ and $1 \leq icol (i) \leq n$ , 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$ .

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

Specifies whether or not the CS representation of the matrix

A

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

$check ='C'$: Checks are carried 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 matrix $A$ .

Constraint: $1 \leq nz \leq n^{2}$ .

Output Parameters

1: $y (n)$ – complex 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,	$trans \neq'N'$ or $'T'$ ,
or	$check \neq'C'$ or $'N'$ .

$ifail = 2$

On entry,	$n < 1$ ,
or	$nz < 1$ ,
or	$nz > n^{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 n$ , 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 within the matrix

A

, is out of order, or has duplicate row and column indices. Call nag_sparse_complex_gen_sort (f11zn) 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}$ , if $trans ='N'$ , or
${‖y - A^{H} x‖}_{\infty} \leq c (n) ε {‖A^{H}‖}_{\infty} {‖x‖}_{\infty}$ , if $trans ='T'$ ,

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_complex_gen_matvec (f11xn) is proportional to nz.

Use of check

It is expected that a common use of nag_sparse_complex_gen_matvec (f11xn) will be to compute the matrix-vector product required in the application of nag_sparse_complex_gen_basic_solver (f11bs) to sparse complex linear systems. In this situation nag_sparse_complex_gen_matvec (f11xn) 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 complex sparse matrix

A

and a vector

x

. It then calls nag_sparse_complex_gen_matvec (f11xn) to compute the matrix-vector product

y = A x

and the conjugate transposed matrix-vector product

y = A^{H} x

Open in the MATLAB editor: f11xn_example

function f11xn_example


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

a = [ 2 + 3i   1 - 4i                             ...
                        1 + 0i  -1 - 2i           ...
      4 + 1i            0 + 1i             1 + 3i ...
                                 0 - 1i    2 - 6i ...
              -2 + 0i                      3 + 1i];
irow = [int64(1) 1   2 2   3 3 3   4 4   5 5];
icol = [int64(1) 2   3 4   1 3 5   4 5   2 5];
x = [ 0.70 + 0.21i;
      0.16 - 0.43i;
      0.52 + 0.97i;
      0.77 + 0.00i;
      0.28 - 0.64i];

% Calculate matrix-vector product
trans = 'N';
check = 'C';
[y, ifail] = f11xn( ...
                    trans, a, irow, icol, check, x);
fprintf('\nMatrix-vector product\n');
disp(y);

% Calculate conjugate transposed matrix-vector product
trans = 'T';
check = 'N';
[y, ifail] = f11xn( ...
                    trans, a, irow, icol, check, x);
fprintf('\nConjugate transposed matrix-vector product\n');
disp(y);

f11xn example results


Matrix-vector product
  -0.7900 + 1.4500i
  -0.2500 - 0.5700i
   3.8200 + 2.2600i
  -3.2800 - 3.7300i
   1.1600 - 0.7800i


Conjugate transposed matrix-vector product
   5.0800 + 1.6800i
  -0.7000 + 4.2900i
   1.1300 - 0.9500i
   0.7000 + 1.5200i
   5.1700 + 1.8300i

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

Chapter Contents

Chapter Introduction

NAG Toolbox