oneapi::mkl::sparse::omatconvert

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-D922A46A-F4B6-49F5-80F6-AAFEE0273976

View Details

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

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
`omatconvert_buffer_size`	Return the size of the temporary workspace.
`omatconvert_analyze`	Count the number of non-zero values (`nnzOut`) in the output sparse matrix.
`omatconvert_get_nnz`	Return the calculated `nnzOut` count of the output sparse matrix.
`omatconvert`	Perform the conversion from the input to the output matrix.

A detailed step-by-step description of the conversion process is as follows:

Beforeomatconvertstages:
- 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 the init_omatconvert_descr API and decide on an algorithm to use through the omatconvert_algenum. The algorithm must not be changed within the series of omatconvert APIs calls.
omatconvert_buffer_sizestage:
- 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_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_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 the omatconvert_descr_t object.
omatconvert_get_nnzstage:
- 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.
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 omatconvert API.
Afteromatconvertstage:
- 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_algenum 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> are csr and coo 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> are csr and coo on both CPU and GPU devices. The <sparse_matrix_type> of spMat_out must be different than that of spMat_in.

alg

The omatconvert_algenum 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 size sizeTempWorkspace bytes used as a temporary workspace for the matrix conversion operation. The workspace must remain valid through the full omatconvert 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 type sycl::buffer<std::uint8_t> *.

For USM inputs, tempWorkspace is a void * 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 the oneapi::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 to omatconvert_analyze and omatconvert. This parameter is obtained from the omatconvert_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 the omatconvert_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

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

oneMKL - Data Parallel C++ Developer Reference

oneapi::mkl::sparse::omatconvert

Description

APIs

Examples