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
where \(A\) is a sparse triangular matrix of size \(m\) rows by \(m\) columns and \(\text{op()}\) is a matrix modifier:
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
andY
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 theoneapi::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>
arecsr
on CPU and GPU devices, andcoo
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 ofldx
based on the providedlayout
of X.For example, if \(\text{op}(X) = X\), i.e
opX == oneapi::mkl::transpose::nontrans
, we would havelayout=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 (forlayout_val=oneapi::mkl::layout::row_major
) or column (forlayout_val=oneapi::mkl::layout::col_major
) dimension ofX
.- ldy
Specifies the leading dimension of matrix
Y
. Must be positive, and at leastcolumns
iflayout_val=oneapi::mkl::layout::row-major
or at least number of rows in \(\text{op}(A)\) iflayout_val=oneapi::mkl::layout::col-major
.- dependencies
A vector of type
std::vector<sycl::event>
containing the list of events that theoneapi::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 ofldy
based on the providedlayout
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