mkl_graph

Developer Reference for Intel® oneAPI Math Kernel Library for C

Download PDF

ID 766684

Date 7/13/2023

Version

Public

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

Visible to Intel only — GUID: GUID-6F53E901-F0CD-4237-B45A-73C4219993B2

View Details

mkl_graph_mxm

Computes a (masked) graph matrix-matrix product.

Syntax

mkl_graph_status_t mkl_graph_mxm (mkl_graph_matrix_t C, mkl_graph_matrix_t M, mkl_graph_accumulator_t accum, mkl_graph_semiring_t semiring, mkl_graph_matrix_t A, mkl_graph_matrix_t B, mkl_graph_descriptor_t desc, mkl_graph_request_t request, mkl_graph_method_t method);

Include Files

mkl_graph.h

Description

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

C<M> := accum(C, opA(A)*opB(B))

where A, B and C are input and output matrices respectively, accum is an optional binary operator to be used as an accumulator for the output matrix, and M is an optional mask for the output matrix. Possible modifications of the operations, including matrix modifiers opA and opB are defined through the operation descriptor desc. The routine supports both single-stage and multistage execution modes via the request parameter. See Graph Operations for a description of the two modes. You can specify a specific method to be used for computations via the method parameter. Use MKL_GRAPH_METHOD_AUTO for an automatic choice.

The operation can be done in-place meaning that the output matrix can be aliased with any of the input matrices or the mask. However, in this case the original data will be replaced.

In the masked case, by default, the pattern of the output matrix (entries present) will be the intersection of the pattern of the mask and the pattern of the non-masked product of matrices A and B. If MKL_GRAPH_MODIFIER_OUTPUT is set to MKL_GRAPH_KEEP_MASK_STRUCTURE in the descriptor desc, the pattern of the output matrix will be exactly the pattern of the mask. The edges missing in the non-masked product are given value zero in the output data type.

For user control of output storage allocation, use multistage execution.

For maximum performance, the following configurations are recommended. For masked multiplication with a sparse mask, multiply CSR times CSC using MKL_GRAPH_METHOD_DOT or MKL_GRAPH_METHOD_ATUO. Use CSR format for the mask and for the output of multistage execution. For non-masked multiplication, or when the mask is dense, multiply matching formats (CSR times CSR or CSC times CSC). Use the same format for the mask and for multistage output, and use MKL_GRAPH_METHOD_GUSTAVSON or MKL_GRAPH_METHOD_ATUO. A “dense” mask means the mask has all possible entries present. It must still be stored in CSR or CSC format using mkl_graph_matrix_set_csr or mkl_graph_matrix_set_csc. For the purpose of these recommendations a transpose flag in the descriptor effectively switches the format, so a CSR input with a transpose flag set is equivalent to CSC when selecting a recommended configuration.

Input Parameters

M: A graph matrix which contains the mask. If NULL, no mask will be used.

NOTE:

Currently the mask is only allowed to have either boolean values or values of the same type as the input matrices (unless MKL_GRAPH_MOD_ONLY_STRUCTURE is set in the descriptor for the mask).
accum: Binary operator to be used as an accumulator. Refer to Graph API Glossary for a list of possible options.

NOTE:

Currently only MKL_GRAPH_ACCUMULATOR_NONE is supported by this routine.
semiring: Algebraic semiring. Refer to Graph API Glossary for a list of possible options.

NOTE:

Currently, the following semirings are supported for this routine for all configurations:

MKL_GRAPH_SEMIRING_PLUS_TIMES_INT32,

MKL_GRAPH_SEMIRING_PLUS_TIMES_INT64,

MKL_GRAPH_SEMIRING_PLUS_TIMES_FP32

MKL_GRAPH_SEMIRING_PLUS_FIRST_FP32

MKL_GRAPH_SEMIRING_PLUS_SECOND_FP32

The semirings MKL_GRAPH_SEMIRING_PLUS_PAIR_INT32 and MKL_GRAPH_SEMIRING_PLUS_PAIR_INT64 are supported with a sparse mask M.

The semiring MKL_GRAPH_SEMIRING_ANY_PAIR_BOOL is supported with no mask or a dense mask.
A: A graph matrix which contains the input matrix A.
B: A graph matrix which contains the input matrix B.

NOTE:

The types of indices and values of the matrices A and B 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 matrices).
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 any of the input matrices or the mask,

MKL_GRAPH_MOD_TRANSPOSE for any of the input matrices,

MKL_GRAPH_MOD_KEEP_MASK_STRUCTURE for the output.
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 an automatic choice, use MKL_GRAPH_METHOD_AUTO. For a dot-product based method (supported only for the masked case with a sparse mask), use MKL_GRAPH_METHOD_DOT. For a Gustavson algorithm (supported only for the non-masked case and dense masks), use MKL_GRAPH_METHOD_GUSTAVSON. A “dense” mask means the mask has all possible entries present. It must still be stored in CSR or CSC format using mkl_graph_matrix_set_csr or mkl_graph_matrix_set_csc. Refer to Graph API Glossary for a list of possible options.

Output Parameters

C: A graph matrix which contains the output matrix C. If matrix C is non-empty on entry to the routine, its data is overwritten by the result of the computations.

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

Product and Performance Information

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

Notice revision #20201201

Parent topic: Graph Operations

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in