oneapi::mkl::sparse::set_matrix

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-6584DB63-DB4E-4681-A02C-21584A837FFE

View Details

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

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

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::set_matrix_property

Description

API

Examples