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.
- 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.
Formats Supported in sparse::trsm() for A
Compressed Sparse Row (CSR) format on CPU/GPU
Coordinate (COO) format on CPU
- 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.cppshare/doc/mkl/examples/sycl/sparse_blas/source/csr_trsm_usm.cpp