Developer Reference for Intel® oneAPI Math Kernel Library for C

ID 766684
Date 12/16/2022
Public

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

Document Table of Contents

Graph API Glossary

The graph API in Intel® oneAPI Math Kernel Library supports different types for indices and values of the objects as well as various options for graph operations, object properties, and error statuses. All of them are implemented in the form of predefined enumerators. They are described below with the lists of all possible options.

mkl_graph_type_t

The following table provides the possible types for data and indices supported by the graph routines.

Type Description

MKL_GRAPH_TYPE_UNSET

A value which stands for “no type was set"

MKL_GRAPH_TYPE_INT32

32-bit integer type

MKL_GRAPH_TYPE_INT64

64-bit integer type

MKL_GRAPH_TYPE_FP32

32-bit floating point type (float, data only)

MKL_GRAPH_TYPE_FP64

64-bit floating point type (double, data only)

MKL_GRAPH_TYPE_BOOL

Boolean type (data only)

mkl_graph_status_t

The returned status for all graph routines can be one of the following:

Status Description

MKL_GRAPH_STATUS_SUCCESS

The routine has been called successfully

MKL_GRAPH_STATUS_NOT_INITIALIZED

One of the graph objects passed to the routine has not been initialized (for example, corresponding mkl_graph_<object>_create routine has not been called).

MKL_GRAPH_STATUS_ALLOC_FAILED

Memory allocation has failed

MKL_GRAPH_STATUS_INVALID_VALUE

One of the input arguments has invalid value (for example, non-optional argument for a graph object has been passed as NULL)

MKL_GRAPH_STATUS_INTERNAL_ERROR

Internal (unclassified) error has been encountered during the execution

MKL_GRAPH_STATUS_NOT_SUPPORTED

A combination of provided parameters is currently not supported by the routine

mkl_graph_semiring_t

Defines which semiring will be used in a graph routine. All names for the semirings are of the form MKL_GRAPH_SEMIRING_<ADDOP>_<MULTOP>_<DATATYPE> where ADDOP and MULTOP define the additive and multiplicative operations of the semiring, respectively, and DATATYPE defines the type of the output. As an example, a standard semiring with single-precision floating point data is called MKL_GRAPH_PLUS_TIMES_FP32. All currently supported semirings are:

  • MKL_GRAPH_SEMIRING_PLUS_TIMES_INT32
  • MKL_GRAPH_SEMIRING_PLUS_TIMES_INT64
  • MKL_GRAPH_SEMIRING_PLUS_TIMES_FP32
  • MKL_GRAPH_SEMIRING_PLUS_TIMES_FP64
  • MKL_GRAPH_SEMIRING_PLUS_FIRST_FP32
  • MKL_GRAPH_SEMIRING_PLUS_SECOND_FP32
  • MKL_GRAPH_SEMIRING_PLUS_PAIR_INT32
  • MKL_GRAPH_SEMIRING_PLUS_PAIR_INT64
  • MKL_GRAPH_SEMIRING_LOR_LAND_BOOL
  • MKL_GRAPH_SEMIRING_MIN_PLUS_INT32
  • MKL_GRAPH_SEMIRING_MIN_FIRST_INT32
  • MKL_GRAPH_SEMIRING_MIN_SECOND_INT32
  • MKL_GRAPH_SEMIRING_ANY_FIRST_INT32
  • MKL_GRAPH_SEMIRING_ANY_FIRST_FP32
  • MKL_GRAPH_SEMIRING_ANY_SECOND_INT32
  • MKL_GRAPH_SEMIRING_ANY_SECOND_FP32
  • MKL_GRAPH_SEMIRING_ANY_PAIR_BOOL

The semiring operations used as ADDOP and MULTOP in the list above are defined as follows:

  • PLUS: (x,y) -> x + y
  • TIMES: (x,y) -> x * y
  • LOR (logical OR): (x,y) -> x | y
  • LAND (logical AND): (x,y) -> x & y
  • MIN: (x,y) -> min(x,y)
  • FIRST: (x,y) -> x. This operation uses only the structure of the second operand in a graph operation (e.g. mkl_graph_vxm) and not the values themselves.
  • SECOND: (x,y) -> y. This operation uses only the structure of the first operand in a graph operation (e.g. mkl_graph_mxv) and not the values themselves.
  • PAIR: (x,y) -> 1. This operation computes the structure of the result without looking at the values of either input. For example, when using the semiring MKL_GRAPH_SEMIRING_PLUS_PAIR_INT32.
  • ANY (used as an “addition” operation only): (x,y) -> x or y. This operation allows for early exit from the computations once any operand (x or y) is present. It is useful, for example, for running algorithm like Breadth-First Search (BFS) where it does not matter which parent to choose for a vertex and the first parent found can be used.

mkl_graph_accumulator_t

Defines which binary operator is used for the accumulation of the output values in a graph operation. If no accumulation is required, use MKL_GRAPH_ACCUMULATOR_NONE. All currently available options are:

  • MKL_GRAPH_ACCUMULATOR_NONE
  • MKL_GRAPH_ACCUMULATOR_PLUS
  • MKL_GRAPH_ACCUMULATOR_MIN

For example, MKL_GRAPH_ACCUMULATOR_PLUS for mkl_graph_mxv without a mask will add the matrix-vector product to the output vector instead of simply overwriting the output vector with the result.

mkl_graph_request_t

This parameter is used in several graph routines to select between single-stage and multi-stage execution. For a simple single-stage execution when the entire output is computed at once, use MKL_GRAPH_REQUEST_COMPUTE_ALL. For multistage execution, use the appropriate other request. Multi-stage execution requires you to allocate memory for the output and pass corresponding pointers to an mkl_graph_<object>_set_<format> routine before each stage. For more details about the multistage execution, refer to Graph Operations and also to the examples for graph functionality. The following table provides the possible values for this parameter.

Value Description

MKL_GRAPH_REQUEST_COMPUTE_ALL

Single-stage execution. All output data are computed during a single call to the routine.

MKL_GRAPH_REQUEST_FILL_NNZ

Multistage execution. Calculate the number of non-zero entries in the output object (matrix or vector) and fill related user-allocated data buffer (rowStart or colStart for a matrix) or set the number of entries (for a vector).

MKL_GRAPH_REQUEST_FILL_ENTRIES

Multistage execution. Fill pre-allocated memory buffers with calculated indices and values of the non-zero entries for the output data (matrix or vector). This request can be used only after a prior call with MKL_GRAPH_REQUEST_FILL_NNZ.

mkl_graph_method_t

A method (algorithm) which can be specified for a particular graph operation. The possible values are listed in the following table.

Value Description

MKL_GRAPH_METHOD_AUTO

Automatic choice of the method

MKL_GRAPH_METHOD_DOT

Dot product method

MKL_GRAPH_METHOD_GUSTAVSON

Gustavson-like method

MKL_GRAPH_METHOD_HASH

Hash based method (not yet supported anywhere)

mkl_graph_descriptor_field_t

Used together with mkl_graph_descriptor_field_value_t to set the value for a descriptor field by calling mkl_graph_descriptor_set_field. When the descriptor is then passed to a graph operation, these (field, value) pairs specify how graph objects in the argument list will be handled in the operation. For example, the descriptor allows you to use the transpose of the first matrix and structural complement of the mask in mkl_graph_mxm without explicitly constructing those objects. Possible values are

Value Description

MKL_GRAPH_FIELD_OUTPUT

The field value modifier will apply to the output of the graph operation

MKL_GRAPH_FIELD_FIRST_INPUT

The field value modifier will apply to the first input of a graph operation

MKL_GRAPH_FIELD_SECOND_INPUT

The field value modifier will apply to the second input of a graph operation

MKL_GRAPH_FIELD_MASK

The field value modifier will apply to the mask in a graph operation

mkl_graph_descriptor_field_value_t

Used together with mkl_graph_descriptor_field_t to set the value for a descriptor field by calling mkl_graph_descriptor_set_field. When the descriptor is then passed to a graph operation, these (field, value) pairs specify how graph objects in the argument list will be handled in the operation. For example, the descriptor allows you to use the transpose of the first matrix and structural complement of the mask in mkl_graph_mxm without explicitly constructing those objects. Possible values are:

Value Description

MKL_GRAPH_MOD_NONE

No modifier

MKL_GRAPH_MOD_COMPLEMENT

Use the structural complement instead of the structure at hand

MKL_GRAPH_MOD_TRANSPOSE

Use the transpose of a matrix

MKL_GRAPH_MOD_REPLACE

Replace the matrix with the output

MKL_GRAPH_MOD_ONLY_STRUCTURE

Do not use the values (equivalent to considering all values equal to 1)

MKL_GRAPH_MOD_KEEP_MASK_STRUCTURE

Return entire mask structure, tolerating zero-weight edges where structurally no edge is present. (This allows for more aggressive optimizations when such edges can be tolerated.)

mkl_graph_property_t

Properties of graph matrices and vectors which can be queried using API routines mkl_graph_<object>_get_property. The possible values are listed in the following table.

Property Name Description

MKL_GRAPH_PROPERTY_NROWS

Type: int64_t. Number of rows in a graph matrix or vector

MKL_GRAPH_PROPERTY_NCOLS

Type: int64_t. Number of columns in a graph matrix or vector

MKL_GRAPH_PROPERTY_NNZ

Type: int64_t. Number of non-zero entries in a graph matrix or vector

MKL_GRAPH_PROPERTY_MATRIX_HAS_CSR

Type: bool. True if the graph matrix has CSR data.

MKL_GRAPH_PROPERTY_MATRIX_HAS_CSC

Type: bool. True if the graph matrix has CSC data.

MKL_GRAPH_PROPERTY_VECTOR_HAS_DENSE

Type: bool. True if the graph vector has data in dense format.

MKL_GRAPH_PROPERTY_VECTOR_HAS_SPARSE

Type: bool. True if the graph vector has data in sparse format.