A newer version of this document is available. Customers should click here to go to the newest version.
Visible to Intel only — GUID: GUID-E8CF1914-91BE-4057-B265-FD0DD3A08D01
Visible to Intel only — GUID: GUID-E8CF1914-91BE-4057-B265-FD0DD3A08D01
oneapi::mkl::sparse::set_matrix_property
Sets matrix properties present in the user provided data provided to the sparse::matrix_handle_t that can serve as optimization hints for library algorithms. Properties are not verified by the library but accepted as truth from the user who specified them.
Description
The oneapi::mkl::sparse::set_matrix_property routine enables the user to set some properties of the user-provided matrix data in the sparse::matrix_handle_t object that can act as hints for the internal algorithms in subsequent library calls.
The oneapi::mkl::sparse::property enum class is defined in the oneapi/mkl/spblas.hpp header file
namespace oneapi::mkl::sparse { enum class property : char { symmetric, sorted }; }
where symmetric refers to the matrix being symmetric and the full pattern is present in the data arrays. The sorted property indicates that the matrix data is sorted in whatever manner is natural to the particular matrix format. See sparse::sort_matrix for more details on sorting. The library will not verify that these properties are true, but will take them as truth from the user. Setting them may affect performance as certain internal optimizations may not need to be done if they are present. The properties may also be set internally by the library when it is applicable (for instance after a call to sparse::sort_matrix.
A common usage model for setting matrix properites is the following:
using namespace oneapi::mkl; sparse::matrix_handle_t spMat = nullptr; sparse::init_matrix_handle(&spMat); sparse::set_csr_data(main_queue, spMat, nrows, nrows, index_base::zero, ia_buffer, ja_buffer, a_buffer); // The csr ia/ja/a arrays are of a full square symmetric matrix that is sorted // with increasing columns in each row, so we can set both symmetric and // sorted property sparse::set_matrix_property(spMat, sparse::property::symmetric); sparse::set_matrix_property(spMat, sparse::property::sorted); sparse::optimize_trsv(main_queue, uplo::lower, transpose::nontrans, diag::nonunit, spMat); sparse::optimize_trsv(main_queue, uplo::upper, transpose::nontrans, diag::nonunit, spMat); sparse::optimize_gemv(main_queue, transpose::nontrans, spMat); // implement some algorithm using trsv/gemv operations (like a preconditioned // conjugate gradient algorithm with symmetric Gauss-Seidel preconditioner) sparse::release_matrix_handle(&spMat);
API
Syntax
namespace oneapi::mkl::sparse { void set_matrix_property(oneapi::mkl::sparse::matrix_handle_t spMat, oneapi::mkl::sparse::property property_value); }
Include Files
oneapi/mkl/spblas.hpp
Input Parameters
- spMat
-
Handle to object containing sparse matrix and other internal data where property will be set. 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. However, for matrices in COO format, property is currently ignored but may enable enhanced performance for that format in the future. - property_value
-
Sparse matrix property being set as in the sparse matrix handle object.
sparse::property::symmetric
data in matrix handle represents a symmetric matrix and has the full pattern and values provided
sparse::property::sorted
data in matrix handle is sorted according to natural state for the given format
Examples
An example of how to use oneapi::mkl::sparse::set_matrix_property can be found in the oneMKL installation directory, under:
share/doc/mkl/examples/sycl/sparse_blas/source/csr_conjugate_gradient.cpp