oneapi::mkl::sparse::set_bsr_data
Takes a matrix handle and the user-provided Block Compressed Sparse Row (BSR) matrix arrays and fills the internal BSR data structure of the matrix handle. This format features a series of dense blocks which can be square or rectangular and with row-major or column major layout and are stored in a compressed sparse row format of blocks.
Description
The oneapi::mkl::sparse::set_bsr_data routine takes a sparse::matrix_handle_t for a sparse matrix of dimensions blk_nrows * row_blk_size -by- blk_ncols * col_blk_size represented in the BSR format, and fills the internal state of the matrix handle with the user provided arrays in BSR format. Refer to the user/library contract for information on the use of the sparse::matrix_handle_t object.
API
Syntax
Using SYCL buffers:
namespace oneapi::mkl::sparse {
void set_bsr_data (
sycl::queue &queue,
oneapi::mkl::sparse::matrix_handle_t spMat,
const std::int64_t blk_nrows,
const std::int64_t blk_ncols,
const std::int64_t blk_nnz,
const std::int64_t row_blk_size,
const std::int64_t col_blk_size,
oneapi::mkl::layout blk_layout,
oneapi::mkl::index_base index,
sycl::buffer<INT_TYPE, 1> &bsr_row_ptr,
sycl::buffer<INT_TYPE, 1> &bsr_col_ind,
sycl::buffer<DATA_TYPE, 1> &bsr_values );
}Using USM pointers:
namespace oneapi::mkl::sparse {
sycl::event set_bsr_data (
sycl::queue &queue,
oneapi::mkl::sparse::matrix_handle_t spMat,
const std::int64_t blk_nrows,
const std::int64_t blk_ncols,
const std::int64_t blk_nnz,
const std::int64_t row_blk_size,
const std::int64_t col_blk_size,
oneapi::mkl::layout blk_layout,
oneapi::mkl::index_base index,
INT_TYPE *bsr_row_ptr,
INT_TYPE *bsr_col_ind,
DATA_TYPE *bsr_values,
const std::vector<sycl::event> &dependencies = {} );
}Include Files
oneapi/mkl/spblas.hpp
Input Parameters
- queue
-
Specifies the SYCL command queue which will be used for SYCL kernels execution.
- spMat
-
Handle to object containing sparse matrix and other internal data for subsequent Sparse BLAS operations.
- blk_nrows
-
Number of block rows of the input matrix.
- blk_ncols
-
Number of block columns of the input matrix.
- blk_nnz
-
Number of blocks (sometimes called number of nonzero blocks) stored in the input matrix.
- row_blk_size
-
Number of rows in each dense block stored in the input matrix.
- col_blk_size
-
Number of cols in each dense block stored in the input matrix.
- blk_layout
-
Layout of the dense blocks (row-major or column-major) stored in the input matrix.
oneapi::mkl::layout::row_major
Row major layout (rows are concatenated one after another)
oneapi::mkl::layout::col_major
Column major layout (columns are concatenated one after another)
- index
-
Indicates how input arrays are indexed.
oneapi::mkl::index_base::zero
Zero-based (C-style) indexing: indices start at 0.
oneapi::mkl::index_base::one
One-based (Fortran-style) indexing: indices start at 1.
- bsr_row_ptr
-
SYCL memory object containing an array of length blk_nrows+1, containing row-wise starting and ending locations of non-zero column block indices and block of values in index-based numbering. Could be a SYCL buffer or a device-accessible USM pointer. Refer to Sparse Storage Formats for a detailed description of bsr_row_ptr.
- bsr_col_ind
-
SYCL memory object which stores an array containing the block column indices in index-based numbering. Could be a SYCL buffer or a device-accessible USM pointer. Refer to Sparse Storage Formats for a detailed description of bsr_col_ind. Array must be at least blk_nnz in length.
- bsr_values
-
SYCL memory object which stores an array containing the blocks of stored matrix elements concatenated one after another of the input matrix in blk_layout format. Could be a SYCL buffer or a device-accessible USM pointer. Refer to Sparse Storage Formats for a detailed description of bsr_values. Array must be at least row_blk_size * col_blk_size * blk_nnz in length.
- dependencies
-
USM API only. A vector of type const std::vector<sycl::event> & containing the list of events that the oneapi::mkl::sparse::set_bsr_data routine depends on.
Summary of Input BSR Arrays
A summary of the BSR input arrays, sizes, and types (see Sparse BLAS Supported Data and Integer Types) is contained in the following table.
For sycl::buffer inputs, the arrays are of type sycl::buffer<T, 1> &.
For USM inputs, the arrays must be device-accessible and of type T *. The recommended USM memory type is described in the following table. In general, using USM device memory will provide a better performance than USM shared, which in turn will give better performance than USM host, but all are supported as they are all device-accessible.
array |
length (elements) |
T |
USM Memory Type |
|---|---|---|---|
bsr_row_ptr |
blk_nrows + 1 |
INT_TYPE |
device accessible (USM device or USM shared or USM host) |
bsr_col_ind |
blk_nnz |
INT_TYPE |
device accessible (USM device or USM shared or USM host) |
bsr_values |
row_blk_size * col_blk_size * blk_nnz |
DATA_TYPE |
device accessible (USM device or USM shared or USM host) |
Output Parameters
- spMat
-
Handle to object containing sparse matrix and other internal data for subsequent SYCL Sparse BLAS operations.
- sycl::event
-
USM API only. A sycl::event that can be used to track the completion of asynchronous events that were enqueued during the API call that continue the chain of events from the input dependencies.