oneapi::mkl::sparse::optimize_trsm#
Performs internal optimizations for oneapi::mkl::sparse::trsm
by
analyzing the provided matrix structure and operation parameters.
Description#
The oneapi::mkl::sparse::optimize_trsm
routine analyzes matrix structure and performs optimizations. Optimized data is then stored in the matrix handle.
We have two versions of oneapi::mkl::sparse::optimize_trsm
; one analyzes the sparse matrix pattern only, and the other version could take information about the layout
and dimenstions of the dense matrices and may allow further optimizations based on the given input.
Note
Refer to Error Handling for a detailed description of the possible exceptions thrown.
API#
Syntax#
Using USM and SYCL buffers:
namespace oneapi::mkl::sparse {
sycl::event optimize_trsm (
sycl::queue &queue,
oneapi::mkl::uplo uplo_val,
oneapi::mkl::transpose opA,
oneapi::mkl::diag diag_val,
oneapi::mkl::sparse::matrix_handle_t A,
const std::vector<sycl::event> &dependencies = {});
sycl::event optimize_trsm (
sycl::queue &queue,
oneapi::mkl::layout layout_val,
oneapi::mkl::uplo uplo_val,
oneapi::mkl::transpose opA,
oneapi::mkl::diag diag_val,
oneapi::mkl::sparse::matrix_handle_t A,
const std::int64_t columns,
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.- 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.
- opA
Specifies operation
op()
on input matrix.oneapi::mkl::transpose::nontrans
Non-transpose,
op(A)
=A
.oneapi::mkl::transpose::trans
Transpose,
op(A)
=A
T.oneapi::mkl::transpose::conjtrans
Conjugate transpose,
op(A)
=A
H.Note
Currently, the only supported case for operation is
oneapi::mkl::transpose::nontrans
.- diag_val
Specifies whether the diagonal used for computations is unit or not.
oneapi::mkl::diag::nonunit
Diagonal elements might not be equal to one.
oneapi::mkl::diag::unit
Diagonal elements are equal to one.
- A
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
The supported cases for
<sparse_matrix_type>
arecsr
on CPU and GPU devices, andcoo
only on CPU device.- columns
Number of columns of matrix
op(X)
andY
of followingsparse::trsm()
routine.- dependencies
A vector of type
std::vector<sycl::event>
containing the list of events that theoneapi::mkl::sparse::optimize_trsm
routine depends on.
Return Values (USM Only)#
- sycl::event
SYCL event that can be waited upon or added as a dependency for the completion of the
optimize_trsm
routine.sycl::event ev_opt = sparse::optimize_trsm(queue, uplo_val, opA, diag_val, A); // Allowed use in case of USM sycl::event ev_opt = sparse::optimize_trsm(queue, uplo_val, opA, diag_val, A, {}); // Allowed use in case of USM sycl::event ev_opt = sparse::optimize_trsm(queue, uplo_val, opA, diag_val, A, dependencies); // Allowed use in case of USM sparse::optimize_trsm(queue, uplo_val, opA, diag_val, A); // OK Recommended use in case of sycl::buffer static_cast<void>(sparse::optimize_trsm(queue, uplo_val, opA, diag_val, A)); // OK Recommended use in case of sycl::buffer (explicitly say we aren't using the event)(will be used in sycl::buffer examples) sparse::optimize_trsm(queue, uplo_val, opA, diag_val, A, {}); // Not recommended in case of sycl::buffer, but supported; sparse::optimize_trsm(queue, uplo_val, opA, diag_val, A, dependencies); // Not recommended in case of sycl::buffer, but supported; sycl::event ev_opt = sparse::optimize_trsm(queue, uplo_val, opA, diag_val, A); // Allowed use in case of sycl::buffer, but most sycl::buffer oneMKL APIs do not have ability to pass in dependencies sycl::event ev_opt = sparse::optimize_trsm(queue, layout_val, uplo_val, opA, diag_val, A, columns); // Allowed use in case of USM sycl::event ev_opt = sparse::optimize_trsm(queue, layout_val, uplo_val, opA, diag_val, A, columns, {}); // Allowed use in case of USM sycl::event ev_opt = sparse::optimize_trsm(queue, layout_val, uplo_val, opA, diag_val, A, columns, dependencies); // Allowed use in case of USM sparse::optimize_trsm(queue, layout_val, uplo_val, opA, diag_val, A, columns); // OK Recommended use in case of sycl::buffer static_cast<void>(sparse::optimize_trsm(queue, layout_val, uplo_val, opA, diag_val, A, columns)); // OK Recommended use in case of sycl::buffer (explicitly say we aren't using the event)(will be used in sycl::buffer examples) sparse::optimize_trsm(queue, layout_val, uplo_val, opA, diag_val, A, columns, {}); // Not recommended in case of sycl::buffer, but supported; sparse::optimize_trsm(queue, layout_val, uplo_val, opA, diag_val, A, columns, dependencies); // Not recommended in case of sycl::buffer, but supported; sycl::event ev_opt = sparse::optimize_trsm(queue, layout_val, uplo_val, opA, diag_val, A, columns); // Allowed use in case of sycl::buffer, but most sycl::buffer oneMKL APIs do not have ability to pass in dependencies