init_csr_matrix

init_csr_matrix#

Initializes a matrix_handle_t object with the provided Compressed Sparse Row (CSR) data.

Description and Assumptions

The oneapi::mkl::sparse::init_csr_matrix function initializes the matrix_handle_t object with the provided data.

In the case of buffers, the reference count of the provided buffer is incremented which extends the lifetime of the underlying buffer until the sparse matrix handle is destroyed with release_sparse_matrix or the data is reset with set_csr_matrix_data.

In the case of USM, the object does not take ownership of the data.

The oneapi::mkl::sparse::init_csr_matrix function defined below takes in the number of non-zero elements in the sparse matrix as an argument. However, in certain math operations where the output is a sparse matrix, e.g., sparse matrix addition (sparse matrix + sparse matrix = sparse matrix), and multiplication of two sparse matrices, the number of non-zero elements in the output sparse matrix are not known in advance and must be calculated as part of the operation API. Such APIs are currently not part of the oneMKL Specification, but will be added in the future. This behavior is currently left to be implementation-defined, but may be clarified in the oneMKL Specification in the future.

See Sparse matrix handle.

init_csr_matrix (Buffer version)#

Syntax

namespace oneapi::mkl::sparse {

    template <typename dataType, typename indexType>
    void init_csr_matrix (sycl::queue                          &queue,
                          oneapi::mkl::sparse::matrix_handle_t *p_smhandle,
                          std::int64_t                         num_rows,
                          std::int64_t                         num_cols,
                          std::int64_t                         nnz,
                          index_base                           index,
                          sycl::buffer<indexType, 1>           row_ptr,
                          sycl::buffer<indexType, 1>           col_ind,
                          sycl::buffer<dataType, 1>            val);

}

Template parameters

dataType: See supported template types.
indexType: See supported template types.

Input parameters

queue: The SYCL command queue which will be used for SYCL kernels execution.
p_smhandle: The address of the p_smhandle object to be initialized. Must only be called on an uninitialized matrix_handle_t object.
num_rows: Number of rows of the provided data val. Must be at least 0.
num_cols: Number of columns of the provided data val. Must be at least 0.
nnz: The number of explicit entries, also known as Number of Non-Zero elements. Must be at least 0.
index: Indicates how input arrays are indexed. The possible options are described in index_base enum class.
row_ptr: Buffer of length at least num_rows+1. Refer to CSR format for detailed description of row_ptr.
col_ind: Buffer of length at least nnz containing the column indices in index-based numbering. Refer to CSR format for detailed description of col_ind.
val: Buffer of length at least nnz. Contains the data of the input matrix which is not implicitly zero. The remaining input values are implicit zeros. Refer to CSR format for detailed description of val.

Output parameters

p_smhandle: On return, the address is updated to point to a newly allocated and initialized matrix_handle_t object that can be filled and used to perform sparse BLAS operations.

Notes

The parameters num_rows, num_cols and nnz may be zero if and only if row_ptr, col_ind and val are zero-sized, otherwise they must be strictly greater than zero.

Throws

This function shall throw the following exceptions if the associated condition is detected. An implementation may throw additional implementation-specific exception(s) in case of error conditions not covered here.

oneapi::mkl::host_bad_alloc
oneapi::mkl::invalid_argument
oneapi::mkl::unimplemented
oneapi::mkl::unsupported_device

init_csr_matrix (USM version)#