oneapi::mkl::sparse::omatconvert#
Performs an out-of-place conversion of user data in a matrix handle into user data in a new handle in a different sparse matrix format.
Description#
Note
Refer to Sparse BLAS Supported Data and Integer Types for a list of supported <DATA_TYPE> and <INT_TYPE> data
and integer types and refer to Error Handling for a detailed description of
the possible exceptions thrown.
The oneapi::mkl::sparse::omatconvert set of routines can be used to convert
a sparse matrix in a given sparse format, referred to as the input matrix,
to another sparse matrix in another format, referred to as the output matrix.
Only out-of-place conversion is supported through these APIs. The only sparse
matrix formats supported by the APIs are compressed sparse row (CSR) and
coordinate list format (COO). The sparse matrix formats for the input and output matrices
must be different; please refer to the sparse::omatcopy
API to perform a copy of the matrix, including potentially changing the index_base in said copy or copying the transpose of the matrix.
The whole conversion process is decomposed in a series of stages. Each stage consists
of a call to one of the omatconvert routines, and may also include some memory allocation
by the user. The API is designed such that minimal data is allocated internally
and users are responsible for most of the required memory allocation. This applies to any temporary
workspace that might be needed during the conversion process and to the memory used for
the data of the output matrix.
The sizes required to allocate the data for the output matrix may depend on parameters that are known a priori, such as the number of rows or columns, and on parameters that might not, such as the number of non-zero elements in the output matrix representation. To address the second situation, APIs are provided to compute the number of non-zero elements in the output matrix before going into the actual conversion.
The stages for the omatconvert algorithm are given below (for the definitions,
see omatconvert APIs and stages):
Stage |
Description |
|---|---|
|
Return the size of the temporary workspace. |
|
Count the number of non-zero values ( |
|
Return the calculated |
|
Perform the conversion from the input to the output matrix. |
A detailed step-by-step description of the conversion process is as follows:
Before
omatconvertstages:Create a handle for the output matrix using
oneapi::mkl::sparse::set_<sparse_matrix_type>_data, where<sparse_matrix_type>represents the desired format for the output matrix.The indexing for the output matrix can be different than that of the input matrix.
At this stage, the number of non-zero elements can be set to 0 and dummy arguments can be used for the matrix representation array (e.g. for CSR: rowptr, colind and values).
Allocate and initialize an
omatconvert_descr_tobject using theinit_omatconvert_descrAPI and decide on an algorithm to use through theomatconvert_algenum. The algorithm must not be changed within the series ofomatconvertAPIs calls.
omatconvert_buffer_sizestage:This is a non-blocking API that may access the input matrix arrays.
Call
omatconvert_buffer_sizeAPI to get the size of the temporary workspace.Allocate the temporary workspace to be used in subsequent stages.
omatconvert_analyzestage:This is a non-blocking asynchronous API that accesses and analyzes the sparsity pattern of the input matrix, and the already known parameters of the output matrix.
Call the
omatconvert_analyze, passing in the temporary workspace allocated in the previous stage.The temporary workspace array is internally stored in the
omatconvert_descr_tobject. Do not modify or free the workspace for the duration of its use for the sparse matrix conversion, which is governed by the lifetime of theomatconvert_descr_tobject.
omatconvert_get_nnzstage:This is a blocking API that returns the non-zero count obtained from the
omatconvert_analyzestage back to the user on the host.Call the
omatconvert_get_nnzAPI to get the non-zero count associated with the output sparse matrix.Allocate the appropriately sized output sparse matrix arrays.
Call the
oneapi::mkl::sparse::set_<sparse_matrix_type>_dataAPI again, this time with the valid, newly allocated row, column, and data arrays of the output sparse matrix. The output 0-/1-based indexing must not be changed at this point, and the number of rows and columns of the matrix must be mathematically consistent with the input matrix sizes at this point.
omatconvertstage:This is a non-blocking asynchronous API that performs the sparse matrix conversion to fill the user-provided output matrix arrays in the requested sparse format.
Call the
omatconvertAPI.
After
omatconvertstage:Release or reuse the
omatconvert_descr_tobject for another appropriate conversion.Release or reuse the temporary workspace arrays allocated for use with this API.
APIs#
Syntax#
enum omatconvert_alg and conversion algorithms#
The omataconvert_alg enum provides users a choice of using specifc algorithms implemented in oneMKL. This enum is defined as:
namespace oneapi::mkl::sparse {
enum class omataconvert_alg : std::int32_t {
default_alg = 0 /* More may be added in the future */
};
}
The list of currently supported algorithms for all conversion configurations is given below:
Conversion type
Supported algorithms
Algoritm description
CSR -> COO
omatconvert_alg::defaultDefault algorithm for the conversion from CSR to COO
COO -> CSR
omatconvert_alg::defaultDefault algorithm for the conversion from COO to CSR. Duplicate elements are condensed.
omatconvert_descr_t object#
omatconvert_descr_t is an operation-specific opaque descriptor object used to
store internal state between calls to the omatconvert set of APIs. Once a given
descriptor object is used in any of the APIs, it should not be changed or
free’d until all calls to omatconvert APIs are completed. A pointer to
the user-provided temporary workspace is stored in this descriptor object through
one of the omatconvert set of APIs, viz., omatconvert_analyze, described
below. There are initialization and release functions associated with this descriptor object.
namespace oneapi::mkl::sparse {
struct omatconvert_descr; /* Forward declaration of opaque omatconvert operation descriptor */
typedef omatconvert_descr *omatconvert_descr_t; /* User-facing type for use in omatconvert APIs */
/* Host-side/non-blocking */
void init_omatconvert_descr(sycl::queue &queue,
omatconvert_descr_t *p_descr);
/* Asynchronous/non-blocking */
sycl::event release_omatconvert_descr(sycl::queue &queue,
omatconvert_descr_t descr,
const std::vector<sycl::event> &dependencies = {});
}
omatconvert APIs and stages#
namespace oneapi::mkl::sparse {
/* Combined USM/sycl::buffer API, host-side/non-blocking */
void omatconvert_buffer_size(
sycl::queue &queue,
matrix_handle_t spMat_in,
matrix_handle_t spMat_out,
omatconvert_alg alg,
omatconvert_descr_t descr,
std::int64_t &sizeTempWorkspace);
/* sycl::buffer API, asynchronous/non-blocking */
sycl::event omatconvert_analyze(
sycl::queue &queue,
matrix_handle_t spMat_in,
matrix_handle_t spMat_out,
omatconvert_alg alg,
omatconvert_descr_t descr,
void *tempWorkspace,
const std::vector<sycl::event> &dependencies = {});
/* USM API, asynchronous/non-blocking */
void omatconvert_analyze(
sycl::queue &queue,
matrix_handle_t spMat_in,
matrix_handle_t spMat_out,
omatconvert_alg alg,
omatconvert_descr_t descr,
sycl::buffer<std::uint8_t, 1> *tempWorkspace);
/* Combined USM/sycl::buffer API, synchronous/blocking */
void omatconvert_get_nnz(
sycl::queue &queue,
matrix_handle_t spMat_in,
matrix_handle_t spMat_out,
omatconvert_alg alg,
omatconvert_descr_t descr,
std::int64_t &nnzOut,
const std::vector<sycl::event> &dependencies = {});
/* Combined USM/sycl::buffer API, asynchronous/non-blocking */
sycl::event omatconvert(
sycl::queue &queue,
matrix_handle_t spMat_in,
matrix_handle_t spMat_out,
omatconvert_alg alg,
omatconvert_descr_t descr,
const std::vector<sycl::event> &dependencies = {});
}
Include Files#
oneapi/mkl/spblas.hpp
Input Parameters#
- queue
Specifies the SYCL command queue that will be used for SYCL kernels execution.
- spMat_in
A handle to an object containing the input sparse matrix and other internal data. Created using one of the
oneapi::mkl::sparse::set_<sparse_matrix_type>_dataroutines.Note
The supported cases for
<sparse_matrix_type>arecsrandcooon both CPU and GPU devices.- spMat_out
A handle to an object containing the output sparse matrix and other internal data. Created using one of the
oneapi::mkl::sparse::set_<sparse_matrix_type>_dataroutines. The dimensions of the sparse matrices in the input and output handles must be the same. At this stage, it is required to have allocated the data for the arrays of this handle.Note
The supported cases for
<sparse_matrix_type>arecsrandcooon both CPU and GPU devices. The<sparse_matrix_type>ofspMat_outmust be different than that ofspMat_in.- alg
The
omatconvert_algenumspecifying the algorithm to use for the conversion. See available options above.- descr
The
omatconvert_descr_tdescriptor object storing input data and operation-specific information and the user-provided temporary workspace. It is created and destroyed using the sparse::init_omatconvert_descr and sparse::release_omatconvert_descr APIs.- tempWorkspace
A SYCL-aware container (
sycl::bufferor device-accessible USM pointer) of sizesizeTempWorkspacebytes used as a temporary workspace for the matrix conversion operation. The workspace must remain valid through the fullomatconvertmulti-stage calls and should not be modified in between calls as long as such calls are being made.For sycl::buffer inputs,
tempWorkspaceis of typesycl::buffer<std::uint8_t> *.For USM inputs,
tempWorkspaceis avoid *pointer that must be device-accessible. The recommended USM memory type for this is USM device for best performance, but USM shared and USM host allocations are also supported as they are device accessible.- dependencies
A vector of type
std::vector<sycl::event> &containing the list of events that theoneapi::mkl::sparse::omatconvertroutine depends on.
Output Parameter#
- sizeTempWorkspace
An integer of type
std::int64_tcontaining the size, in bytes, of the temporary workspace,tempWorkspace, that must be allocated for calls toomatconvert_analyzeandomatconvert. This parameter is obtained from theomatconvert_buffer_sizeAPI.- nnzOut
An integer of type
std::int64_tcontaining the format specific number of non-zeros in the output matrix, to be used to allocate the output matrix arrays. This parameter is obtained from theomatconvert_get_nnzAPI.- spMat_out
On return, the data for the sparse matrix will be filled according to the requested
<sparse_matrix_type>.
Return Values#
sycl::eventSYCL event that can be waited upon or added as a dependency for the completion of the
omatconvertroutine.
Examples#
Examples on how to use oneapi::mkl::sparse::omatconvert and other related APIs,
with SYCL buffers or USM, can be found in the oneMKL installation
directory, under:
share/doc/mkl/examples/sycl/sparse_blas/source/csr2coo_omatconvert.cpp
share/doc/mkl/examples/sycl/sparse_blas/source/coo2csr_omatconvert_usm.cpp