Sparse BLAS Routines

oneMKL - Data Parallel C++ Developer Reference

Download PDF

ID 772045

Date 6/24/2024

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-1A747491-6D0C-42FD-B4D1-0C5BBE9854B3

View Details

Sparse BLAS Routines

The Intel® oneAPI Math Kernel Library (oneMKL) provides a C++ with SYCL interface to some of the Sparse BLAS routines. This section describes such Sparse BLAS routines included in oneMKL.

The Sparse BLAS domain provides basic operations on sparse matrices and vectors. The fundamental object that encompasses the sparse matrix and that is used in the Sparse BLAS domain is sparse::matrix_handle_t. See Sparse BLAS Matrix Handle Contract between User and Library for a discussion of the way that library APIs will interact with the handle as well as the usage contract with regards to the matrix handle for both users and the library. The currently supported sparse matrix formats in the sparse::matrix_handle_t object can be found in Sparse Storage Formats. In addition to this main sparse matrix handle, there are other data structures and enum objects that are part of the sparse BLAS domain, listed in the table below.

Structure/enum	Description
sparse::matrix_handle_t	Pointer to an opaque sparse matrix object
sparse::property	User-provided matrix data guarantees (such as sorted input data)
sparse::omatadd_alg	Algorithm `enum` for use with the sparse::omatadd API
sparse::omatadd_descr_t	Pointer to an opaque descriptor object for use with the sparse::omatadd API
sparse::matrix_view_descr	`enum` for use with the sparse::set_matmat_data API
sparse::matmat_request	`enum` for use with the sparse::matmat API
sparse::matmat_descr_t	Pointer to an opaque descriptor object for use with the sparse::matmat API
sparse::omatconvert_alg	Algorithm `enum` for use with the sparse::omatconvert API
sparse::omatconvert_descr_t	Pointer to an opaque descriptor object for use with the sparse::omatconvert API

The routines that enable these Sparse BLAS operations can be separated into 4 groups:

State management routines
Analysis routines (also called inspector stage or optimize stage routines)
Execution routines
Helper routines.

The state management routines include initialization, destruction and APIs for setting data, formats and properties in the different sparse objects like the sparse::matrix_handle_t or sparse::matmat_descr_t.

In an analysis routine, the library inspects the matrix properties including size, sparsity pattern and available parallelism and can create new data structures or copies of the user data which applies matrix format or structure changes to enable a more optimized algorithm for the desired operation. The user data is not changed by any such analysis or optimizations. The optimizations created in the analysis routines may be reused by multiple execution routines to improve performance. For a given matrix, an analysis routine would typically be called a single time for each operation whereas the corresponding execution routines may be called multiple times.

The execution routines are where the actual matrix-matrix, matrix-vector operations take place and may use the data, optimizations and properties stored in the handle to perform the desired operation.

The helper routines operate on the data in the matrix handle and may include things like data copy/transpose into other handles, sorting of data within a handle, or converting the sparse matrix format from one handle to another.

State Management Routines	Data Types	Description
sparse::init_matrix_handle	N/A	Initialize a `sparse::matrix_handle_t` object
sparse::release_matrix_handle	N/A	Release a `sparse::matrix_handle_t` object
sparse::set_csr_data	float, double, std::complex<float>, std::complex<double>	Set internal representation of `sparse::matrix_handle_t` to compressed sparse row (CSR) format with user-provided CSR data arrays.
sparse::set_coo_data	float, double, std::complex<float>, std::complex<double>	Set internal representation of `sparse::matrix_handle_t` to coordinate (COO) format with user-provided COO data arrays.
sparse::set_matrix_property	N/A	Set special properties of user-provided marix data in `sparse::matrix_handle_t` that can provide hints for optimizations.
sparse::init_omatadd_descr	N/A	Initialize a `sparse::omatadd_descr_t` object. For use with sparse::omatadd
sparse::release_omatadd_descr	N/A	Release a `sparse::omatadd_descr_t` object. For use with sparse::omatadd
sparse::init_matmat_descr	N/A	Initialize a `sparse::matmat_descr_t` object. For use with sparse::matmat
sparse::set_matmat_data	N/A	Populate a `sparse::matmat_descr_t` object with desired operation description. For use with sparse::matmat
sparse::get_matmat_data	N/A	Query the operation description housed in a `sparse::matmat_descr_t` object. For use with sparse::matmat
sparse::release_matmat_descr	N/A	Release a `sparse::matmat_descr_t` object. For use with sparse::matmat
sparse::init_omatconvert_descr	N/A	Initialize a `sparse::omatconvert_descr_t` object. For use with sparse::omatconvert
sparse::release_omatconvert_descr	N/A	Release a `sparse::omatconvert_descr_t` object. For use with sparse::omatconvert

Analysis Routines	Data Types	Description
sparse::optimize_gemv	N/A	Perform internal optimizations for the sparse::gemv operation.
sparse::optimize_trmv	N/A	Perform internal optimizations for the sparse::trmv operation.
sparse::optimize_trsv	N/A	Perform internal optimizations for the sparse::trsv operation.
sparse::optimize_trsm	N/A	Perform internal optimizations for the sparse::trsm operation.

Execution Routines	Data Types	Description
sparse::gemv	float, double, std::complex<float>, std::complex<double>	General sparse matrix-dense vector product
sparse::gemvdot	float, double, std::complex<float>, std::complex<double>	General sparse matrix-dense vector product with fused dot product
sparse::symv	float, double, std::complex<float>, std::complex<double>	Symmetric sparse matrix-dense vector product
sparse::trmv	float, double, std::complex<float>, std::complex<double>	Triangular sparse matrix-dense vector product
sparse::trsv	float, double, std::complex<float>, std::complex<double>	Triangular solve of sparse matrix against a dense vector.
sparse::gemm	float, double, std::complex<float>, std::complex<double>	General sparse matrix-dense matrix product
sparse::trsm	float, double, std::complex<float>, std::complex<double>	Triangular solve of sparse matrix against a dense matrix.
sparse::omatadd	float, double, std::complex<float>, std::complex<double>	General sparse matrix-sparse matrix addition
sparse::matmat	float, double, std::complex<float>, std::complex<double>	General sparse matrix-sparse matrix product
sparse::matmatd	float, double, std::complex<float>, std::complex<double>	Product of two sparse matrices with a dense result

Helper Routines	Data Types	Description
sparse::omatcopy	float, double, std::complex<float>, std::complex<double>	General sparse matrix out-of-place copy/transposition into a new matrix handle
sparse::omatconvert	float, double, std::complex<float>, std::complex<double>	General sparse matrix out-of-place conversion into a new matrix handle
sparse::sort_matrix	float, double, std::complex<float>, std::complex<double>	General sparse matrix sort of matrix format in matrix handle
sparse::update_diagonal_values	float, double, std::complex<float>, std::complex<double>	Change values of the main diagonal entries in matrix handle

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

oneMKL - Data Parallel C++ Developer Reference

Sparse BLAS Routines