Developer Reference for Intel® oneAPI Math Kernel Library - C

Developer Reference

  • 0.10
  • 10/21/2020
  • Public Content
Contents

mkl_graph_mxv

Computes a (masked) graph matrix-vector product.

Syntax

mkl_graph_status_t
mkl_graph_mxv (mkl_graph_vector_t
w
,
mkl_graph_vector_t
mask
,
mkl_graph_accumulator_t
accum
,
mkl_graph_semiring_t
semiring
,
mkl_graph_matrix_t
A
,
mkl_graph_vector_t
u
,
mkl_graph_descriptor_t
desc
,
mkl_graph_request_t
request
,
mkl_graph_method_t
method
);
Include Files
  • mkl_graph.h
Description
The
mkl_graph_mxv
 routine computes a (masked) graph matrix-vector product defined as 
w<mask> := accum(w, op(A)*u)
where
u
,
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.
 The expression
op(
A
)*
u
 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 will be 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.
Even if the input vector is dense, the output vector can be sparse if the matrix has empty rows.
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 rows and sparse output is expected.
Input Parameters
mask
A graph vector which contains the mask. If NULL, no mask is used.
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.
The following accumulators are supported:
MKL_GRAPH_ACCUMULATOR_NONE
,
MKL_GRAPH_ACCUMULATOR_PLUS
 (only for
MKL_GRAPH_SEMIRING_PLUS_SECOND_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_SECOND_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.
The following semirings are supported:
MKL_GRAPH_SEMIRING_PLUS_TIMES_INT32
,
MKL_GRAPH_SEMIRING_PLUS_TIMES_FP32
,
MKL_GRAPH_SEMIRING_PLUS_SECOND_FP32
 (for a dense input vector),
MKL_GRAPH_SEMIRING_MIN_SECOND_INT32
 (for a dense input vector),
MKL_GRAPH_SEMIRING_MIN_PLUS_INT32
,
MKL_GRAPH_SEMIRING_ANY_SECOND_INT32
,
MKL_GRAPH_SEMIRING_ANY_SECOND_FP32
,
MKL_GRAPH_SEMIRING_ANY_PAIR_BOOL
 (for a sparse input vector).
A
A graph matrix which contains the input matrix
A
.
u
A graph vector which contains the input vector
u
.
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.
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.
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.
Optimization Notice
Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.
Notice revision #20110804
This notice covers the following instruction sets: SSE2, SSE4.2, AVX2, AVX-512.

Product and Performance Information

1

Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserverd for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.

Notice revision #20110804