Developer Reference for Intel® oneAPI Math Kernel Library for C

ID 766684
Date 3/31/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

mkl_graph_vxm

Computes a (masked) graph vector-matrix product.

Syntax

mkl_graph_status_t mkl_graph_vxm (mkl_graph_vector_t w, mkl_graph_vector_t mask, mkl_graph_accumulator_t accum, mkl_graph_semiring_t semiring, mkl_graph_vector_t u, mkl_graph_matrix_t A, mkl_graph_descriptor_t desc, mkl_graph_request_t request, mkl_graph_method_t method);

Include Files
  • mkl_graph.h

Description

The mkl_graph_vxm routine computes a (masked) graph vector-matrix product defined as

w<mask> := accum(w, u*op(A))

where u and w are input and output vectors respectively, A is the graph matrix, accum is the optional binary operator to be used as an accumulator for the output vector and mask is an optional mask for the output vector. Possible modifications of the operation, including the matrix modifier op, are defined through the operation descriptor desc. The routine supports both single-stage and multistage execution modes (see Graph Operations) via the request parameter. Opposite to mkl_graph_mxv which works with column vectors, the input and output vectors for mkl_graph_vxm are considered to be row vectors.

The expression u*op(A) is evaluated over the algebraic semiring defined from the semiring parameter. The operation can be done in-place, meaning that the output vector can be aliased with the input vector or the mask. However, in this case the original data is replaced.

The method parameter is reserved for future use when an advanced user will be able to specify a particular method to be used for computations. Currently, only MKL_GRAPH_METHOD_AUTO is supported.

NOTE:

Even if the input vector is dense, the output vector can be sparse if the matrix has empty columns.

NOTE:

Multistage execution requires you to set the format of the output vector. Currently only the format matching the input vector is supported. In particular, you should allocate enough space for a dense vector and call mkl_graph_vector_set_dense in the multistage execution flow if the input vector is dense, even if the matrix has empty columns and sparse output is expected.

Input Parameters
mask

A graph vector which contains the mask. If NULL, no mask is used.

NOTE:

Currently mask can only be used when the input vector is sparse.

accum

Binary operator to be used as an accumulator. Refer to Graph API Glossary for a list of possible options.

NOTE:

The following accumulators are supported:

MKL_GRAPH_ACCUMULATOR_NONE,

MKL_GRAPH_ACCUMULATOR_PLUS, (only for MKL_GRAPH_SEMIRING_PLUS_FIRST_FP32 with a dense input vector and out of place output vector)

MKL_GRAPH_ACCUMULATOR_MIN, (only for MKL_GRAPH_SEMIRING_MIN_PLUS_INT32 and MKL_GRAPH_SEMIRING_MIN_FIRST_INT32 with a dense input vector and out of place output vector)

semiring

Algebraic semiring. Refer to Graph API Glossary for a list of possible options.

NOTE:

The following semirings are supported:

MKL_GRAPH_SEMIRING_PLUS_TIMES_INT32,

MKL_GRAPH_SEMIRING_PLUS_TIMES_FP32,

MKL_GRAPH_SEMIRING_PLUS_FIRST_FP32 (for a dense input vector),

MKL_GRAPH_SEMIRING_MIN_FIRST_INT32 (for a dense input vector),

MKL_GRAPH_SEMIRING_MIN_PLUS_INT32,

MKL_GRAPH_SEMIRING_ANY_FIRST_INT32,

MKL_GRAPH_SEMIRING_ANY_FIRST_FP32

A

A graph matrix which contains the input matrix A.

u

A graph vector which contains the input vector u.

NOTE:

The types of indices and values of the matrix A and input vector u should match (except for the values which can be unused if a corresponding flag MKL_GRAPH_MOD_ONLY_STRUCTURE is set in the descriptor for one of the input arguments).

desc

An operation descriptor. Refer to Graph API Glossary for a list of possible options. If NULL, no extra modifiers are used for the operation.

NOTE:

Currently it is allowed to set:

MKL_GRAPH_MOD_ONLY_STRUCTURE for input matrix or input vector,

MKL_GRAPH_MOD_TRANSPOSE for the input matrix,

MKL_GRAPH_MOD_COMPLEMENT for the mask.

request

An operation request as defined in the multi-stage execution model. For single-stage execution, use MKL_GRAPH_REQUEST_COMPUTE_ALL. For multistage execution, stages MKL_GRAPH_REQUEST_FILL_NNZ and MKL_GRAPH_REQUEST_FILL_ENTRIES should be used. Refer to Graph API Glossary for a list of possible options.

method

A method which should be used for computing the result. For automatic choice, use MKL_GRAPH_METHOD_AUTO. Refer to Graph API Glossary for a list of possible options.

NOTE:

Currently only MKL_GRAPH_METHOD_AUTO is supported by this routine.

Output Parameters
w

A graph vector which contains the output vector w. If vector w is non-empty on entry to the routine, its data is overwritten by the result of the computations. Also, in this case the type of values of w must match the type of the semiring values.

Return Values

The function returns a value indicating whether the operation was successful or not and why. Refer to Graph API Glossary for a list of possible options.

Product and Performance Information

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.

Notice revision #20201201