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
omatconvert
stages: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_t
object using theinit_omatconvert_descr
API and decide on an algorithm to use through theomatconvert_alg
enum
. The algorithm must not be changed within the series ofomatconvert
APIs calls.
omatconvert_buffer_size
stage:This is a non-blocking API that may access the input matrix arrays.
Call
omatconvert_buffer_size
API to get the size of the temporary workspace.Allocate the temporary workspace to be used in subsequent stages.
omatconvert_analyze
stage: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_t
object. 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_t
object.
omatconvert_get_nnz
stage:This is a blocking API that returns the non-zero count obtained from the
omatconvert_analyze
stage back to the user on the host.Call the
omatconvert_get_nnz
API 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>_data
API 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.
omatconvert
stage: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
omatconvert
API.
After
omatconvert
stage:Release or reuse the
omatconvert_descr_t
object 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::default
Default algorithm for the conversion from CSR to COO
COO -> CSR
omatconvert_alg::default
Default 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>_data
routines.Note
The supported cases for
<sparse_matrix_type>
arecsr
andcoo
on 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>_data
routines. 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>
arecsr
andcoo
on both CPU and GPU devices. The<sparse_matrix_type>
ofspMat_out
must be different than that ofspMat_in
.- alg
The
omatconvert_alg
enum
specifying the algorithm to use for the conversion. See available options above.- descr
The
omatconvert_descr_t
descriptor 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::buffer
or device-accessible USM pointer) of sizesizeTempWorkspace
bytes used as a temporary workspace for the matrix conversion operation. The workspace must remain valid through the fullomatconvert
multi-stage calls and should not be modified in between calls as long as such calls are being made.For sycl::buffer inputs,
tempWorkspace
is of typesycl::buffer<std::uint8_t> *
.For USM inputs,
tempWorkspace
is 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::omatconvert
routine depends on.
Output Parameter#
- sizeTempWorkspace
An integer of type
std::int64_t
containing the size, in bytes, of the temporary workspace,tempWorkspace
, that must be allocated for calls toomatconvert_analyze
andomatconvert
. This parameter is obtained from theomatconvert_buffer_size
API.- nnzOut
An integer of type
std::int64_t
containing 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_nnz
API.- spMat_out
On return, the data for the sparse matrix will be filled according to the requested
<sparse_matrix_type>
.
Return Values#
sycl::event
SYCL event that can be waited upon or added as a dependency for the completion of the
omatconvert
routine.
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