Developer Reference

  • 0.9
  • 09/09/2020
  • Public Content
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.

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 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