Graph API Glossary

Developer Reference for Intel® oneAPI Math Kernel Library for C

Download PDF

ID 766684

Date 3/31/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-BBD5EA5D-1D63-4577-B4D5-9807F8C2236E

View Details

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.

Parent topic: Graph Routines

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Developer Reference for Intel® oneAPI Math Kernel Library for C

Graph API Glossary

mkl_graph_type_t

mkl_graph_status_t

mkl_graph_semiring_t

mkl_graph_accumulator_t

mkl_graph_request_t

mkl_graph_method_t

mkl_graph_descriptor_field_t

mkl_graph_descriptor_field_value_t

mkl_graph_property_t