oneapi::mkl::sparse::trsm#

Solves a system of linear equations with multiple right-hand sides (RHS) for a triangular sparse matrix.

Description#

The oneapi::mkl::sparse::trsm routine solves the sparse triangular system

\[\text{op}(A)\cdot Y = \alpha \cdot \text{op}(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 matrices \(X\) and \(Y\) are stored with row-major or column-major layout and have an appropriate number of rows and columns number of columns for computing sparse::trsm() operation, that is, \(\text{op}(X)\) and \(Y\) are of dimensions \(m\) rows by \(columns\) columns. The matrix \(\text{op}(X)\) is input right hand side data and \(Y\) is the resulting output matrix.

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, for 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.

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.

  • While it can make sense to pass in the same array for both RHS (\(X\)) and solution (\(Y\)) in order to update the RHS in-place, we currently do not support in-place sparse::trsm() operation.

API#

Syntax#

Using SYCL buffers:

namespace oneapi::mkl::sparse {
    void trsm (
        sycl::queue &queue,
        oneapi::mkl::layout layout_val,
        oneapi::mkl::transpose opA,
        oneapi::mkl::transpose opX,
        oneapi::mkl::uplo uplo_val,
        oneapi::mkl::diag diag_val,
        const DATA_TYPE alpha,
        oneapi::mkl::sparse::matrix_handle_t A,
        sycl::buffer<DATA_TYPE, 1> &X,
        const std::int64_t columns,
        const std::int64_t ldx,
        sycl::buffer<DATA_TYPE, 1> &Y,
        const std::int64_t ldy);
}

Using USM pointers:

namespace oneapi::mkl::sparse {
    sycl::event trsm(
        sycl::queue &queue,
        oneapi::mkl::layout layout_val,
        oneapi::mkl::transpose opA,
        oneapi::mkl::transpose opX,
        oneapi::mkl::uplo uplo_val,
        oneapi::mkl::diag diag_val,
        const DATA_TYPE alpha,
        oneapi::mkl::sparse::matrix_handle_t A,
        const DATA_TYPE *X,
        const std::int64_t columns,
        const std::int64_t ldx,
        DATA_TYPE *Y,
        const std::int64_t ldy,
        const std::vector<sycl::event> &dependencies = {});
}

Include Files#

  • oneapi/mkl/spblas.hpp

Input Parameters#

queue

Specifies the SYCL command queue that will be used for SYCL kernels execution.

layout_val

Specifies the storage scheme in memory for the dense matrices. Note that this layout applies to both X and Y dense matrices.

opA

Specifies operation op() on the sparse input matrix, \(A\).

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.

opX

Specifies operation op() on the dense input matrix, \(X\).

oneapi::mkl::transpose::nontrans

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

oneapi::mkl::transpose::trans

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

oneapi::mkl::transpose::conjtrans

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

Note

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

uplo_val

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.

diag_val

Specifies whether 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.

alpha

Specifies the scalar, \(\alpha\).

A

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

Note

The supported cases for <sparse_matrix_type> are csr on CPU and GPU devices, and coo only on CPU device.

X

SYCL buffer or device-accessible USM pointer for the right hand side dense matrix. \(\text{op}(X)\) is of dimension \(m\) by columns with a leading dimension stride of ldx based on the provided layout of X.

For example, if \(\text{op}(X) = X\), i.e opX == oneapi::mkl::transpose::nontrans, we would have

layout=oneapi::mkl::layout::col-major

layout=oneapi::mkl::layout::row-major

nrows of \(\text{op}(X)\)

ldx

m

ncols of \(\text{op}(X)\)

columns

ldx

columns

Number of columns of \(\text{op}(X)\) and \(Y\) matrices.

ldx

Specifies the leading dimension of matrix X. Must be positive, and larger than or equal to the actual usable row (for layout_val=oneapi::mkl::layout::row_major) or column (for layout_val=oneapi::mkl::layout::col_major) dimension of X.

ldy

Specifies the leading dimension of matrix Y. Must be positive, and at least columns if layout_val=oneapi::mkl::layout::row-major or at least number of rows in \(\text{op}(A)\) if layout_val=oneapi::mkl::layout::col-major.

dependencies

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

Output Parameters#

Y

SYCL buffer or device-accessible USM pointer for the dense matrix solution of the triangular solve. \(Y\) is of dimension \(m\) by columns with a leading dimension stride of ldy based on the provided layout of Y.

layout=oneapi::mkl::layout::col-major

layout=oneapi::mkl::layout::row-major

nrows of \(Y\)

ldy

m (number of rows in \(\text{op}(A)\) and \(A\))

ncols of \(Y\)

columns

ldy

Return Values (USM Only)#

sycl::event

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

Examples#

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

share/doc/mkl/examples/sycl/sparse_blas/source/csr_trsm.cpp
share/doc/mkl/examples/sycl/sparse_blas/source/csr_trsm_usm.cpp