oneapi::mkl::sparse::trsv

Solves a system of linear equations for a triangular sparse matrix.

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::trsv routine solves the sparse triangular system

\[\text{op}(A)\cdot y = x\]

where \(A\) is a sparse triangular matrix of size \(m\) rows by \(m\) columns and \(\text{op()}\) is a matrix modifier:

\[\begin{split}\text{op}(A) = \begin{cases} A,& \text{ oneapi::mkl::transpose::nontrans}\\ A^{T},& \text{ oneapi::mkl::transpose::trans}\\A^{H},& \text{ oneapi::mkl::transpose::conjtrans} \end{cases}\end{split}\]

The dense vectors \(x\) and \(y\) must be at least of length \(m\). The vector \(x\) is input right hand side data and math:y is the resulting output vector.

Note

While it can make sense to pass the same array in for both rhs, \(x\), and solution, \(y\), to update the rhs in place, we currentlydo not guarantee that this will always work.

For a given matrix decomposition into lower, diagonal and upper parts \(A = L + D + U\), the triangular solve with one of oneapi::mkl::uplo::lower or oneapi::mkl::uplo::upper selected will perform the appropriate forward or backward substitution using respectively \(\text{op}(L+D)\) or \(\text{op}(D+U)\) for oneapi::mkl::diag::nonunit or if using oneapi::mkl::diag::unit, will perform the appropriate forward or backward substitution for \(\text{op}(L+I)\) or \(\text{op}(I+U)\) where \(I\) is the identity matrix.

API

Syntax

Note

Currently, complex types are not supported.

Using SYCL buffers:

namespace oneapi::mkl::sparse {
    void trsv (
        sycl::queue &queue,
        oneapi::mkl::uplo uplo_flag,
        oneapi::mkl::transpose transpose_flag,
        oneapi::mkl::diag diag_flag,
        oneapi::mkl::sparse::matrix_handle_t handle,
        sycl::buffer<DATA_TYPE, 1> &x,
        sycl::buffer<DATA_TYPE, 1> &y)
}

Using USM pointers:

namespace oneapi::mkl::sparse {
    sycl::event trsv(
        sycl::queue &queue,
        oneapi::mkl::uplo uplo_flag,
        oneapi::mkl::transpose transpose_flag,
        oneapi::mkl::diag diag_flag,
        oneapi::mkl::sparse::matrix_handle_t handle,
        DATA_TYPE *x,
        DATA_TYPE *y,
        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.

uplo_flag

Specifies which part of the matrix is to be processed.

oneapi::mkl::uplo::lower

The lower triangular matrix part is processed.

oneapi::mkl::uplo::upper

The upper triangular matrix part is processed.

transpose_flag

Specifies operation op() on input matrix.

oneapi::mkl::transpose::nontrans

Non-transpose, \(\text{op}(A) = A\).

oneapi::mkl::transpose::trans

Transpose, \(\text{op}(A) = A^{T}\).

oneapi::mkl::transpose::conjtrans

Conjugate transpose, \(\text{op}(A) = A^{H}\).

Note

Currently, the only supported case for operation is oneapi::mkl::transpose::nontrans.

diag_flag

Specifies if the diagonal used for computations is unit or based on provided matrix data.

oneapi::mkl::diag::nonunit

Diagonal elements are used as provided in the sparse matrix.

oneapi::mkl::diag::unit

The value of one is substituted for the diagonal elements in the triangular solve algorithm.

Note

If oneapi::mkl::diag::nonunit is selected, all diagonal values must be present in the sparse matrix sparsity profile and must not be zero valued. This is not necessary for the oneapi::mkl::diag::unit case. An exception of type onemkl::invalid_value() will be thrown in case this is violated.

handle

Handle to object containing sparse matrix and other internal data. Created using one of the oneapi::mkl::sparse::set_<sparse_matrix_type>_data routines.

Note

Currently, the only supported case for <sparse_matrix_type> is csr.

x

SYCL buffer or device-accessible USM pointer of size at least equal to the number of columns of input matrix if transpose_flag = oneapi::mkl::transpose::nontrans and at least the number of rows of input matrix otherwise. It is the input vector x

dependencies

A vector of type std::vector<sycl::event> containing the list of events that the oneapi::mkl::sparse::trsv routine depends on.

Output Parameters

y

SYCL buffer or device-accessible USM pointer of size at least equal to the number of rows of the input matrix if transpose_flag = oneapi::mkl::transpose::nontrans and at least the number of columns of the input matrix otherwise. The solution of the triangular solve is filled into this array.

Return Values (USM Only)

sycl::event

SYCL event which can be waited upon or added as a dependency for the completion of the trsv routine.

Examples

An example of how to use oneapi::mkl::sparse::trsv with SYCL buffers or USM can be found in the oneMKL installation directory, under:

examples/dpcpp/sparse_blas/source/sparse_trsv.cpp
examples/dpcpp/sparse_blas/source/sparse_trsv_usm.cpp