S3L_mat_vec_mult

Description

Sun S3L provides six matrix vector multiplication routines, which compute one or more instances of a matrix vector product. For each instance, these routines perform the operations listed in Table 8-10.

In these descriptions, conj[A] denotes the conjugate of A.

Syntax

The C and Fortran syntax for S3L_mat_vec_mult are shown below.

C/C++ Syntax

Example 8-7

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_mat_vec_mult(y, A, x, y_vector_axis, row_axis, col_axis, x_vector_axis)
S3L_mat_vec_mult_noadd(y, A, x, y_vector_axis, row_axis, col_axis, x_vector_axis)
S3L_mat_vec_mult_addto(y, A, x, v, y_vector_axis, row_axis, col_axis,
x_vector_axis)
S3L_mat_vec_mult_c1(y, A, x, y_vector_axis, row_axis, col_axis, x_vector_axis)
S3L_mat_vec_mult_c1_noadd(y, A, x, y_vector_axis, row_axis, col_axis,
x_vector_axis)
S3L_mat_vec_mult_c1_addto(y, A, x, v, y_vector_axis, row_axis, col_axis,
x_vector_axis)
    S3L_array_t        y
    S3L_array_t        A
    S3L_array_t        x
    S3L_array_t        v
    int                y_vector_axis
    int                row_axis
    int                col_axis
    int                x_vector_axis

F77/F90 Syntax

Example 8-8

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_mat_vec_mult(y, A, x, y_vector_axis, row_axis, col_axis, x_vector_axis,
ier)
S3L_mat_vec_mult_noadd(y, A, x, y_vector_axis, row_axis, col_axis, x_vector_axis,
ier)
S3L_mat_vec_mult_addto(y, A, x, v, y_vector_axis, row_axis, col_axis,
x_vector_axis, ier)
S3L_mat_vec_mult_c1(y, A, x, y_vector_axis, row_axis, col_axis, x_vector_axis,
ier)
S3L_mat_vec_mult_c1_noadd(y, A, x, y_vector_axis, row_axis, col_axis,
x_vector_axis, ier)
S3L_mat_vec_mult_c1_addto(y, A, x, v, y_vector_axis, row_axis, col_axis,
x_vector_axis, ier)
    integer*8          y
    integer*8          A
    integer*8          x
    integer*8          v
    integer*4          y_vector_axis
    integer*4          row_axis
    integer*4          col_axis
    integer*4          x_vector_axis
    integer*4          ier

Input

• y - Array handle for an S3L parallel array of rank >= 1. Two matrix vector multiplication routines, S3L_mat_vec_mult and S3L_mat_vec_mult_c1 add the contents of this array to the product of Ax. All matrix vector multiplication routines use y as the destination array, as described in the Output section.

• A - Array handle for an S3L parallel array of rank one greater than that of y. It contains one or more instances of the matrix A, defined by axes row_axis (which counts the rows) and col_axis (which counts the columns).

  The remaining axes must match the instance axes of y in length and order of declaration. Thus, each matrix in A corresponds to a vector in y. The contents of A are not changed during execution

• x - Array handle for an S3L parallel array of the same rank as y. It contains one or more instances of x, the vector that will be multiplied by the matrix A, embedded along axis x_vector_axis.

  Axis x_vector_axis of x must have the same length as axis col_axis of A. The remaining axes of x must match the instance axes of y in length and order of declaration. Thus, each vector in x corresponds to a vector in y. The contents of x are not changed during execution.

• v - Array handle for an S3L parallel array of the same rank and shape as y. This argument is used only in the S3L_mat_vec_mult_addto and S3L_mat_vec_mult_c1_addto calls. It contains one or more instances of the vector v, which will be added to the matrix vector product, embedded along axis y_vector_axis. The contents of v are not changed during execution, unless v is the same variable as y.

  Note: For S3L_mat_vec_mult_addto and S3L_mat_vec_mult_c1_addto, the argument v can be identical to the argument y.

• y_vector_axis - Scalar integer variable that specifies the axis of y and v along which the elements of the embedded vectors lie. For C/C++ programs, this argument must be nonnegative and less than the rank of y. For F77/F90 programs, it must be greater than zero and less than or equal to the rank of y.

• row_axis - Scalar integer variable. It counts the rows of the embedded matrix or matrices. For C/C++ programs, this argument must be nonnegative and less than the rank of A. For F77/F90 programs, it must be greater than zero and less than or equal to the rank of A.

• col_axis - Scalar integer variable that counts the columns of the embedded matrix or matrices. For C/C++ programs, this argument must be nonnegative and less than the rank of A. For F77/F90 programs, it must be greater than zero and less than or equal to the rank of A.

• x_vector_axis - Scalar integer variable that specifies the axis of x along which the elements of the embedded vectors lie. For C/C++ programs, this argument must be nonnegative and less than the rank of y. For F77/F90 programs, it must be greater than zero and less than or equal to the rank of x.

Output

These functions use the following arguments for output:

• y - Array handle for an S3L array of rank >= 1. This array contains one or more instances of the destination vector y embedded along the axis y_vector_axis. This axis must have the same length as axis row_axis of A. Upon completion, each vector instance is overwritten by the result of the matrix vector multiplication call.

• ier (Fortran only) - When called from a Fortran program, these functions return error status in ier.

Error Handling

On success, the S3L_mat_vec_mult routines return S3L_SUCCESS.

The S3L_mat_vec_mult routines perform generic checking of the validity of the arrays they accept as arguments. If an array argument contains an invalid or corrupted value, the function terminates and an error code indicating which value of the array handle was invalid is returned. See Appendix A of this manual for a detailed list of these error codes.

In addition, the following conditions will cause these functions to terminate and return the associated error code:

• S3L_ERR_MATCH_RANK - The parallel arrays do not have the same rank.

• S3L_ERR_MATCH_EXTENTS - The lengths of corresponding axes do not match.

• S3L_ERR_MATCH_DTYPE - The arguments are not all of the same data type and precision.

• S3L_ERR_ARG_AXISNUM - row_axis and/or col_axis contains a bad axis number. For C/C++ program calls, each of these parameters must be nonnegative and less than the rank of A. For F77/F90 calls, they must be greater than zero and less than or equal to the rank of A.

• S3L_ERR_CONJ_INVAL - Conjugation was requested, but the data supplied was not of type S3L_complex_t or S3L_dcomplex_t.

Examples

../examples/s3l/dense_matrix_ops/matvec_mult.c
../examples/s3l/dense_matrix_ops-f/matvec_mult.f

Related Functions

S3L_inner_prod(3)
S3L_2_norm(3)
S3L_outer_prod(3)
S3L_mat_mult(3)