spsv#

Solves a system of linear equations where the coefficients are described by a triangular sparse matrix.

Description and Assumptions

The oneapi::math::sparse::spsv routine solves a system of linear equations for a square matrix:

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

where:

\(\alpha\) is a scalar,
\(x\) and \(y\) are dense vectors of size m,
\(\text{op}(A)\) is a transformed sparse matrix of size m-by-m,
\(\text{op}()\) is the transform operation using the following description:

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

spsv_descr#

Definition

namespace oneapi::math::sparse {

    struct spsv_descr;
    using spsv_descr_t = spsv_descr*;

}

Description

Defines spsv_descr_t as an opaque pointer to the incomplete type spsv_descr. Each backend may provide a different implementation of the type spsv_descr. The spsv_descr_t object persists through the various stages of the spsv operation to house relevant state, optimizations and workspaces.

init_spsv_descr#

Syntax

namespace oneapi::math::sparse {

    void init_spsv_descr (sycl::queue                       &queue,
                          oneapi::math::sparse::spsv_descr_t *p_spsv_descr);

}

Input parameters

queue: The SYCL command queue which will be used for SYCL kernels execution.
p_spsv_descr: The address of the p_spsv_descr object to be initialized. Must only be called on an uninitialized spsv_descr_t object.

Output parameters

p_spsv_descr: On return, the address is updated to point to a newly allocated and initialized spsv_descr_t object that can be used to perform spsv.

Throws

This function shall throw the following exceptions if the associated condition is detected. An implementation may throw additional implementation-specific exception(s) in case of error conditions not covered here.

oneapi::math::host_bad_alloc
oneapi::math::invalid_argument
oneapi::math::unimplemented
oneapi::math::unsupported_device

release_spsv_descr#

Syntax

namespace oneapi::math::sparse {

    sycl::event release_spsv_descr (sycl::queue                       &queue,
                                    oneapi::math::sparse::spsv_descr_t spsv_descr,
                                    const std::vector<sycl::event>    &dependencies = {});

}

Input parameters

queue: The SYCL command queue which will be used for SYCL kernels execution.
spsv_descr: Descriptor initialized with init_spsv_descr.
dependencies: List of events to depend on before starting asynchronous tasks that access data on the device. Defaults to no dependencies.

Return Values

Output event that can be waited upon or added as a dependency for the completion of the function.

Throws

oneapi::math::invalid_argument
oneapi::math::unimplemented
oneapi::math::unsupported_device

spsv_alg#

Syntax

namespace oneapi::math::sparse {

    enum class spsv_alg {
        default_alg,
        no_optimize_alg,
    };

}

Description

These algorithm enums are provided in case backends would like to implement various different algorithms for the operation. Behavior of the algorithms (e.g., bitwise reproducibility, atomics usage) and the preconditions to using specific algorithms (e.g. sortedness of matrix arrays) is implementation-defined and must be documented in the library implementing the oneAPI specification.

spsv#

Syntax

namespace oneapi::math::sparse {

    void spsv_buffer_size(
        sycl::queue                                &queue,
        oneapi::math::transpose                     opA,
        const void*                                alpha,
        oneapi::math::sparse::matrix_view           A_view,
        oneapi::math::sparse::matrix_handle_t       A_handle,
        oneapi::math::sparse::dense_vector_handle_t x_handle,
        oneapi::math::sparse::dense_vector_handle_t y_handle,
        oneapi::math::sparse::spsv_alg              alg,
        oneapi::math::sparse::spsv_descr_t          spsv_descr,
        std::size_t                                &temp_buffer_size);

    void spsv_optimize(
        sycl::queue                                &queue,
        oneapi::math::transpose                     opA,
        const void*                                alpha,
        oneapi::math::sparse::matrix_view           A_view,
        oneapi::math::sparse::matrix_handle_t       A_handle,
        oneapi::math::sparse::dense_vector_handle_t x_handle,
        oneapi::math::sparse::dense_vector_handle_t y_handle,
        oneapi::math::sparse::spsv_alg              alg,
        oneapi::math::sparse::spsv_descr_t          spsv_descr,
        sycl::buffer<std::uint8_t, 1>              workspace);

    sycl::event spsv_optimize(
        sycl::queue                                &queue,
        oneapi::math::transpose                     opA,
        const void*                                alpha,
        oneapi::math::sparse::matrix_view           A_view,
        oneapi::math::sparse::matrix_handle_t       A_handle,
        oneapi::math::sparse::dense_vector_handle_t x_handle,
        oneapi::math::sparse::dense_vector_handle_t y_handle,
        oneapi::math::sparse::spsv_alg              alg,
        oneapi::math::sparse::spsv_descr_t          spsv_descr,
        void*                                      workspace,
        const std::vector<sycl::event>             &dependencies = {});

    sycl::event spsv(
        sycl::queue                                &queue,
        oneapi::math::transpose                     opA,
        const void*                                alpha,
        oneapi::math::sparse::matrix_view           A_view,
        oneapi::math::sparse::matrix_handle_t       A_handle,
        oneapi::math::sparse::dense_vector_handle_t x_handle,
        oneapi::math::sparse::dense_vector_handle_t y_handle,
        oneapi::math::sparse::spsv_alg              alg,
        oneapi::math::sparse::spsv_descr_t          spsv_descr,
        const std::vector<sycl::event>             &dependencies = {});

}

Notes

spsv_buffer_size and spsv_optimize must be called at least once before spsv with the same arguments. spsv can then be called multiple times. Calling spsv_optimize on the same descriptor can reset some of the descriptor’s data such as the workspace.
In the general case, not calling the functions in the order specified above is undefined behavior. Not calling spsv_buffer_size or spsv_optimize at least once with a given descriptor will throw a oneapi::math::uninitialized exception. Calling spsv with arguments not matching spsv_optimize will throw an oneapi::math::invalid_argument exception, unless stated otherwise.
The data of the dense handle x_handle and scalar alpha can be reset before each call to spsv. Changing the data of the sparse handle A_handle is undefined behavior.
The data must be available on the device when calling spsv_optimize by using event dependencies if needed.
spsv_optimize and spsv are asynchronous.
The algorithm defaults to spsv_alg::default_alg if a backend does not support the provided algorithm.
The container type of all the handles and workspace must be consistent and use either USM pointers or SYCL buffers.

Input Parameters

queue: The SYCL command queue which will be used for SYCL kernels execution.
opA: Specifies operation op() on the input matrix. The possible options are described in transpose enum class.
alpha: Host or USM pointer representing \(\alpha\). The USM allocation can be on the host or device. Must be a host pointer if SYCL buffers are used. Must be of the same type as the handles’ data type.
A_view: Specifies which part of the handle should be read as described by matrix_view. The type_view field must be matrix_descr::triangular. The diag_view field can be diag::nonunit or diag::unit.
A_handle: Sparse matrix handle object representing \(A\).
x_handle: Dense vector handle object representing \(x\).
y_handle: Dense vector handle object representing \(y\).
alg: Specifies the spsv algorithm to use.
spsv_descr: Initialized spsv descriptor.
temp_buffer_size: Output buffer size in bytes.
workspace: Workspace buffer or USM pointer, must be at least of size temp_buffer_size bytes and the address aligned on the size of the handles’ data type.

If it is a buffer, its lifetime is extended until the spsv descriptor is released or the workspace is reset by spsv_optimize. The workspace cannot be a sub-buffer.

If it is a USM pointer, it must not be free’d until the corresponding spsv has completed. The data must be accessible on the device.
dependencies: List of events to depend on before starting asynchronous tasks that access data on the device. Ignored if buffers are used. Defaults to no dependencies.

Output Parameters

temp_buffer_size: Output buffer size in bytes. A temporary workspace of at least this size must be allocated to perform the specified spsv.
y_handle: Dense vector handle object representing \(y\), result of the spsv operation.

Return Values

Output event that can be waited upon or added as a dependency for the completion of the function. May be an empty event if buffers are used.

Throws

These functions shall throw the following exceptions if the associated condition is detected. An implementation may throw additional implementation-specific exception(s) in case of error conditions not covered here.

oneapi::math::computation_error
oneapi::math::device_bad_alloc
oneapi::math::invalid_argument
oneapi::math::unimplemented
oneapi::math::uninitialized
oneapi::math::unsupported_device

Parent topic: Sparse BLAS

spsv

Contents

spsv#

spsv_descr#

init_spsv_descr#

release_spsv_descr#

spsv_alg#

spsv#