From 8b413e1c48470e50d063296e79feb11f1929ca07 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Wed, 21 Feb 2024 18:41:44 +0000 Subject: [PATCH 01/52] [oneMKL][spblas] Update sparse blas API Update sparse blas API to better support other backends. --- .../domains/sparse_linear_algebra.inc.rst | 3 +- .../spblas/data_types/create_coo_matrix.rst | 241 +++++++++++ .../spblas/data_types/create_csr_matrix.rst | 239 +++++++++++ .../spblas/data_types/create_dense_matrix.rst | 192 +++++++++ .../spblas/data_types/create_dense_vector.rst | 162 ++++++++ .../spblas/data_types/data_handles.rst | 122 ++++++ .../data_types/destroy_dense_matrix.rst | 55 +++ .../data_types/destroy_dense_vector.rst | 55 +++ .../data_types/destroy_sparse_matrix.rst | 55 +++ .../spblas/data_types/format-descriptions.rst | 149 +++++++ .../spblas/data_types/set_coo_matrix_data.rst | 209 ++++++++++ .../spblas/data_types/set_csr_matrix_data.rst | 207 +++++++++ .../data_types/set_dense_matrix_data.rst | 176 ++++++++ .../data_types/set_dense_vector_data.rst | 144 +++++++ .../spblas/data_types/set_matrix_property.rst | 95 +++++ .../domains/spblas/format-descriptions.rst | 154 ------- .../oneMKL/source/domains/spblas/gemm.rst | 335 --------------- .../source/domains/spblas/gemmoptimize.rst | 208 --------- .../oneMKL/source/domains/spblas/gemv.rst | 218 ---------- .../oneMKL/source/domains/spblas/gemvdot.rst | 237 ----------- .../source/domains/spblas/gemvoptimize.rst | 96 ----- .../source/domains/spblas/matrix_view.rst | 134 ++++++ .../source/domains/spblas/matrixinit.rst | 75 ---- .../source/domains/spblas/operations/spmm.rst | 393 ++++++++++++++++++ .../source/domains/spblas/operations/spmv.rst | 371 +++++++++++++++++ .../source/domains/spblas/operations/spsv.rst | 333 +++++++++++++++ .../domains/spblas/releasematrixhandle.rst | 89 ---- .../source/domains/spblas/setcoostructure.rst | 263 ------------ .../source/domains/spblas/setcsrstructure.rst | 261 ------------ .../oneMKL/source/domains/spblas/spblas.rst | 85 +--- .../source/domains/spblas/supported-types.rst | 26 +- .../oneMKL/source/domains/spblas/symv.rst | 223 ---------- .../source/domains/spblas/symvoptimize.rst | 98 ----- .../oneMKL/source/domains/spblas/trmv.rst | 250 ----------- .../source/domains/spblas/trmvoptimize.rst | 110 ----- .../oneMKL/source/domains/spblas/trsv.rst | 217 ---------- .../source/domains/spblas/trsvoptimize.rst | 111 ----- 37 files changed, 3363 insertions(+), 3028 deletions(-) create mode 100644 source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst create mode 100644 source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst create mode 100644 source/elements/oneMKL/source/domains/spblas/data_types/create_dense_matrix.rst create mode 100644 source/elements/oneMKL/source/domains/spblas/data_types/create_dense_vector.rst create mode 100644 source/elements/oneMKL/source/domains/spblas/data_types/data_handles.rst create mode 100644 source/elements/oneMKL/source/domains/spblas/data_types/destroy_dense_matrix.rst create mode 100644 source/elements/oneMKL/source/domains/spblas/data_types/destroy_dense_vector.rst create mode 100644 source/elements/oneMKL/source/domains/spblas/data_types/destroy_sparse_matrix.rst create mode 100644 source/elements/oneMKL/source/domains/spblas/data_types/format-descriptions.rst create mode 100644 source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst create mode 100644 source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst create mode 100644 source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst create mode 100644 source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst create mode 100644 source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_property.rst delete mode 100644 source/elements/oneMKL/source/domains/spblas/format-descriptions.rst delete mode 100644 source/elements/oneMKL/source/domains/spblas/gemm.rst delete mode 100644 source/elements/oneMKL/source/domains/spblas/gemmoptimize.rst delete mode 100644 source/elements/oneMKL/source/domains/spblas/gemv.rst delete mode 100644 source/elements/oneMKL/source/domains/spblas/gemvdot.rst delete mode 100644 source/elements/oneMKL/source/domains/spblas/gemvoptimize.rst create mode 100644 source/elements/oneMKL/source/domains/spblas/matrix_view.rst delete mode 100644 source/elements/oneMKL/source/domains/spblas/matrixinit.rst create mode 100644 source/elements/oneMKL/source/domains/spblas/operations/spmm.rst create mode 100644 source/elements/oneMKL/source/domains/spblas/operations/spmv.rst create mode 100644 source/elements/oneMKL/source/domains/spblas/operations/spsv.rst delete mode 100644 source/elements/oneMKL/source/domains/spblas/releasematrixhandle.rst delete mode 100644 source/elements/oneMKL/source/domains/spblas/setcoostructure.rst delete mode 100644 source/elements/oneMKL/source/domains/spblas/setcsrstructure.rst delete mode 100644 source/elements/oneMKL/source/domains/spblas/symv.rst delete mode 100644 source/elements/oneMKL/source/domains/spblas/symvoptimize.rst delete mode 100644 source/elements/oneMKL/source/domains/spblas/trmv.rst delete mode 100644 source/elements/oneMKL/source/domains/spblas/trmvoptimize.rst delete mode 100644 source/elements/oneMKL/source/domains/spblas/trsv.rst delete mode 100644 source/elements/oneMKL/source/domains/spblas/trsvoptimize.rst diff --git a/source/elements/oneMKL/source/domains/sparse_linear_algebra.inc.rst b/source/elements/oneMKL/source/domains/sparse_linear_algebra.inc.rst index 23916970f..27182437a 100644 --- a/source/elements/oneMKL/source/domains/sparse_linear_algebra.inc.rst +++ b/source/elements/oneMKL/source/domains/sparse_linear_algebra.inc.rst @@ -23,9 +23,10 @@ Sparse Linear Algebra In the execution stage, multiple routine calls can take advantage of the analysis stage data in order to improve performance. +.. TODO: Reword and remove onemkl_sparse_matrix_handle_t In order to save information in between calls to Sparse BLAS computation routines, - the :ref:`onemkl_sparse_matrix_handle_t` type is introduced, that is essentially + the ``onemkl_sparse_matrix_handle_t`` type is introduced, that is essentially an opaque pointer, used to store data related to initial sparse matrix and data obtained during analysis stage. diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst new file mode 100644 index 000000000..9d3320a0d --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst @@ -0,0 +1,241 @@ +.. SPDX-FileCopyrightText: 2024 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_sparse_create_coo_matrix: + +create_coo_matrix +================= + +Initializes a ``matrix_handle_t`` object with the provided COO data. + +.. rubric:: Description and Assumptions + +The ``oneapi::mkl::sparse::create_coo_matrix`` function initializes the +``matrix_handle_t`` object with the provided data. + +In the case of buffers, the reference count of the provided buffer is +incremented which extends the lifetime of the underlying buffer until the +``smhandle`` is destroyed with ``destroy_sparse_matrix`` or the data is reset with +``set_coo_matrix_data``. + +In the case of USM, the object does not take ownership of the data. + +The ``oneapi::mkl::sparse::create_coo_matrix`` function defined below takes in +the number of non-zero elements in the sparse matrix as an argument. However, in +certain math operations where the output is a sparse matrix, e.g., sparse matrix +addition (sparse matrix + sparse matrix = sparse matrix), and multiplication of +two sparse matrices, the number of non-zero elements in the output sparse matrix +is not known in advance and must be calculated as part of the operation/API. +Such APIs are currently not a part of the current oneMKL Specification, but will +be added in the future. Therefore, it is important for the ``create_coo_matrix`` +API to be able to handle multiple calls to build the sparse matrix as function +arguments become known and arrays are allocated with the correct sizes. In +particular, the ``create_coo_matrix`` API must handle the case where the number +of non-zero elements in the matrix are unknown and the matrix arrays are +``nullptr`` or zero-sized ``sycl::buffer`` objects as applicable. This behavior +is currently left to be implementation-defined, but may be clarified in the +oneMKL Specification in the future. + +See :ref:`onemkl_sparse_matrix_handle`. + +.. _onemkl_sparse_create_coo_matrix_buffer: + +create_coo_matrix (Buffer version) +---------------------------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + template + void create_coo_matrix (sycl::queue &queue, + oneapi::mkl::sparse::matrix_handle_t *p_smhandle, + std::int64_t num_rows, + std::int64_t num_cols, + std::int64_t nnz, + index_base index, + sycl::buffer &row_ind, + sycl::buffer &col_ind, + sycl::buffer &val); + + } + +.. container:: section + + .. rubric:: Template parameters + + fpType + See :ref:`supported template types`. + + intType + See :ref:`supported template types`. + +.. container:: section + + .. rubric:: Input parameters + + queue + The SYCL command queue which will be used for SYCL kernels execution. + + p_smhandle + The address of the ``p_smhandle`` object to be initialized. Must only be + called on an uninitialized ``matrix_handle_t`` object. + + num_rows + Number of rows of the provided data ``val``. Must be at least 0. + + num_cols + Number of columns of the provided data ``val``. Must be at least 0. + + nnz + Number of non-zero entries in the matrix (which may include explicit + zeros). Must be at least 0. + + index + Indicates how input arrays are indexed. The possible options are described + in :ref:`onemkl_enum_index_base` enum class. + + row_ind + Buffer of length ``nnz`` containing the row indices in ``index``-based + numbering. Refer to :ref:`onemkl_sparse_coo` format for detailed + description of ``row_ind``. + + col_ind + Buffer of length ``nnz`` containing the column indices in ``index``-based + numbering. Refer to :ref:`onemkl_sparse_coo` format for detailed + description of ``col_ind``. + + val + Buffer of length ``nnz`` containing non-zero elements (and possibly + explicit zeros) of the input matrix. Refer to :ref:`onemkl_sparse_coo` + format for detailed description of ``val``. + +.. container:: section + + .. rubric:: Output parameters + + p_smhandle + On return, the address is updated to point to a newly allocated and + initialized ``matrix_handle_t`` object that can be filled and used to + perform sparse BLAS operations. + +.. container:: section + + .. rubric:: 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. + + | :ref:`oneapi::mkl::device_bad_alloc` + | :ref:`oneapi::mkl::host_bad_alloc` + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::unsupported_device` + +.. _onemkl_sparse_create_coo_matrix_usm: + +create_coo_matrix (USM version) +------------------------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + template + void create_coo_matrix (sycl::queue &queue, + oneapi::mkl::sparse::matrix_handle_t *p_smhandle, + std::int64_t num_rows, + std::int64_t num_cols, + std::int64_t nnz, + index_base index, + intType *row_ind, + intType *col_ind, + fpType *val); + + } + +.. container:: section + + .. rubric:: Template parameters + + fpType + See :ref:`supported template types`. + + intType + See :ref:`supported template types`. + +.. container:: section + + .. rubric:: Input parameters + + queue + The SYCL command queue which will be used for SYCL kernels execution. + + p_smhandle + The address of the ``p_smhandle`` object to be initialized. Must only be + called on an uninitialized ``matrix_handle_t`` object. + + num_rows + Number of rows of the provided data ``val``. Must be at least 0. + + num_cols + Number of columns of the provided data ``val``. Must be at least 0. + + nnz + Number of non-zero entries in the matrix (which may include explicit + zeros). Must be at least 0. + + index + Indicates how input arrays are indexed. The possible options are described + in :ref:`onemkl_enum_index_base` enum class. + + row_ind + USM pointer of length ``nnz`` containing the row indices in + ``index``-based numbering. Refer to :ref:`onemkl_sparse_coo` format for + detailed description of ``row_ind``. The data must be accessible on the + device. + + col_ind + USM pointer of length ``nnz`` containing the column indices in + ``index``-based numbering. Refer to :ref:`onemkl_sparse_coo` format for + detailed description of ``col_ind``. The data must be accessible on the + device. + + val + USM pointer of length ``nnz`` containing non-zero elements (and possibly + explicit zeros) of the input matrix. Refer to :ref:`onemkl_sparse_coo` + format for detailed description of ``val``. The data must be accessible on + the device. + +.. container:: section + + .. rubric:: Output parameters + + p_smhandle + On return, the address is updated to point to a newly allocated and + initialized ``matrix_handle_t`` object that can be filled and used to + perform sparse BLAS operations. + +.. container:: section + + .. rubric:: 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. + + | :ref:`oneapi::mkl::device_bad_alloc` + | :ref:`oneapi::mkl::host_bad_alloc` + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::unsupported_device` + +**Parent topic:** :ref:`onemkl_sparse_data_handles` diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst new file mode 100644 index 000000000..52c449b60 --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst @@ -0,0 +1,239 @@ +.. SPDX-FileCopyrightText: 2024 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_sparse_create_csr_matrix: + +create_csr_matrix +================= + +Initializes a ``matrix_handle_t`` object with the provided CSR data. + +.. rubric:: Description and Assumptions + +The ``oneapi::mkl::sparse::create_csr_matrix`` function initializes the +``matrix_handle_t`` object with the provided data. + +In the case of buffers, the reference count of the provided buffer is +incremented which extends the lifetime of the underlying buffer until the +``smhandle`` is destroyed with ``destroy_sparse_matrix`` or the data is reset with +``set_csr_matrix_data``. + +In the case of USM, the object does not take ownership of the data. + +The ``oneapi::mkl::sparse::create_csr_matrix`` function defined below takes in +the number of non-zero elements in the sparse matrix as an argument. However, in +certain math operations where the output is a sparse matrix, e.g., sparse matrix +addition (sparse matrix + sparse matrix = sparse matrix), and multiplication of +two sparse matrices, the number of non-zero elements in the output sparse matrix +is not known in advance and must be calculated as part of the operation/API. +Such APIs are currently not a part of the current oneMKL Specification, but will +be added in the future. Therefore, it is important for the ``create_csr_matrix`` +API to be able to handle multiple calls to build the sparse matrix as function +arguments become known and arrays are allocated with the correct sizes. In +particular, the ``create_csr_matrix`` API must handle the case where the number +of non-zero elements in the matrix are unknown and the matrix arrays are +``nullptr`` or zero-sized ``sycl::buffer`` objects as applicable. This behavior +is currently left to be implementation-defined, but may be clarified in the +oneMKL Specification in the future. + +See :ref:`onemkl_sparse_matrix_handle`. + +.. _onemkl_sparse_create_csr_matrix_buffer: + +create_csr_matrix (Buffer version) +---------------------------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + template + void create_csr_matrix (sycl::queue &queue, + oneapi::mkl::sparse::matrix_handle_t *p_smhandle, + std::int64_t num_rows, + std::int64_t num_cols, + std::int64_t nnz, + index_base index, + sycl::buffer &row_ptr, + sycl::buffer &col_ind, + sycl::buffer &val); + + } + +.. container:: section + + .. rubric:: Template parameters + + fpType + See :ref:`supported template types`. + + intType + See :ref:`supported template types`. + +.. container:: section + + .. rubric:: Input parameters + + queue + The SYCL command queue which will be used for SYCL kernels execution. + + p_smhandle + The address of the ``p_smhandle`` object to be initialized. Must only be + called on an uninitialized ``matrix_handle_t`` object. + + num_rows + Number of rows of the provided data ``val``. Must be at least 0. + + num_cols + Number of columns of the provided data ``val``. Must be at least 0. + + nnz + Number of non-zero entries in the matrix (which may include explicit + zeros). Must be at least 0. + + index + Indicates how input arrays are indexed. The possible options are described + in :ref:`onemkl_enum_index_base` enum class. + + row_ptr + Buffer of length ``num_rows+1``. Refer to :ref:`onemkl_sparse_csr` format + for detailed description of ``row_ptr``. + + col_ind + Buffer of length ``nnz`` containing the column indices in ``index``-based + numbering. Refer to :ref:`onemkl_sparse_csr` format for detailed + description of ``col_ind``. + + val + Buffer of length ``nnz`` containing non-zero elements (and possibly + explicit zeros) of the input matrix. Refer to :ref:`onemkl_sparse_csr` + format for detailed description of ``val``. + +.. container:: section + + .. rubric:: Output parameters + + p_smhandle + On return, the address is updated to point to a newly allocated and + initialized ``matrix_handle_t`` object that can be filled and used to + perform sparse BLAS operations. + +.. container:: section + + .. rubric:: 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. + + | :ref:`oneapi::mkl::device_bad_alloc` + | :ref:`oneapi::mkl::host_bad_alloc` + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::unsupported_device` + +.. _onemkl_sparse_create_csr_matrix_usm: + +create_csr_matrix (USM version) +------------------------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + template + void create_csr_matrix (sycl::queue &queue, + oneapi::mkl::sparse::matrix_handle_t *p_smhandle, + std::int64_t num_rows, + std::int64_t num_cols, + std::int64_t nnz, + index_base index, + intType *row_ptr, + intType *col_ind, + fpType *val); + + } + +.. container:: section + + .. rubric:: Template parameters + + fpType + See :ref:`supported template types`. + + intType + See :ref:`supported template types`. + +.. container:: section + + .. rubric:: Input parameters + + queue + The SYCL command queue which will be used for SYCL kernels execution. + + p_smhandle + The address of the ``p_smhandle`` object to be initialized. Must only be + called on an uninitialized ``matrix_handle_t`` object. + + num_rows + Number of rows of the provided data ``val``. Must be at least 0. + + num_cols + Number of columns of the provided data ``val``. Must be at least 0. + + nnz + Number of non-zero entries in the matrix (which may include explicit + zeros). Must be at least 0. + + index + Indicates how input arrays are indexed. The possible options are described + in :ref:`onemkl_enum_index_base` enum class. + + row_ptr + USM pointer of length ``num_rows+1``. Refer to :ref:`onemkl_sparse_csr` + format for detailed description of ``row_ptr``. The data must be + accessible on the device. + + col_ind + USM pointer of length ``nnz`` containing the column indices in + ``index``-based numbering. Refer to :ref:`onemkl_sparse_csr` format for + detailed description of ``col_ind``. The data must be accessible on the + device. + + val + USM pointer of length ``nnz`` containing non-zero elements (and possibly + explicit zeros) of the input matrix. Refer to :ref:`onemkl_sparse_csr` + format for detailed description of ``val``. The data must be accessible on + the device. + +.. container:: section + + .. rubric:: Output parameters + + p_smhandle + On return, the address is updated to point to a newly allocated and + initialized ``matrix_handle_t`` object that can be filled and used to + perform sparse BLAS operations. + +.. container:: section + + .. rubric:: 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. + + | :ref:`oneapi::mkl::device_bad_alloc` + | :ref:`oneapi::mkl::host_bad_alloc` + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::unsupported_device` + +**Parent topic:** :ref:`onemkl_sparse_data_handles` diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_matrix.rst new file mode 100644 index 000000000..752c8da5a --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_matrix.rst @@ -0,0 +1,192 @@ +.. SPDX-FileCopyrightText: 2024 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_sparse_create_dense_matrix: + +create_dense_matrix +=================== + +Initializes a ``dense_matrix_handle_t`` object with the provided data. + +.. rubric:: Description and Assumptions + +The ``oneapi::mkl::sparse::create_dense_matrix`` function initializes the +``dense_matrix_handle_t`` object with the provided data. + +In the case of buffers, the reference count of the provided buffer is +incremented which extends the lifetime of the underlying buffer until the +``dmhandle`` is destroyed with ``destroy_dense_matrix`` or the data is reset +with ``set_dense_matrix_data``. + +In the case of USM, the object does not take ownership of the data. + +See :ref:`onemkl_sparse_dense_matrix_handle`. + +.. _onemkl_sparse_create_dense_matrix_buffer: + +create_dense_matrix (Buffer version) +------------------------------------ + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + template + void create_dense_matrix (sycl::queue &queue, + oneapi::mkl::sparse::dense_matrix_handle_t *p_dmhandle, + std::int64_t num_rows, + std::int64_t num_cols, + std::int64_t ld, + layout dense_layout, + sycl::buffer &val); + + } + +.. container:: section + + .. rubric:: Template parameters + + fpType + See :ref:`supported template types`. + +.. container:: section + + .. rubric:: Input parameters + + queue + The SYCL command queue which will be used for SYCL kernels execution. + + p_dmhandle + The address of the ``p_dmhandle`` object to be initialized. Must only be + called on an uninitialized ``dense_matrix_handle_t`` object. + + num_rows + Number of rows of the provided data ``val``. Must be at least 0. + + num_cols + Number of columns of the provided data ``val``. Must be at least 0. + + ld + Leading dimension of the provided data ``val``. Must be at least + ``num_rows`` if column major layout is used or at least ``num_cols`` if + row major layout is used. + + dense_layout + Specify whether the data uses row major or column major. + + val + Buffer of length ``ld*num_cols`` if column major is used or + ``ld*num_rows`` if row major is used. Holds the data to initialize + ``p_dmhandle`` with. + +.. container:: section + + .. rubric:: Output parameters + + p_dmhandle + On return, the address is updated to point to a newly allocated and + initialized ``dense_matrix_handle_t`` object that can be filled and used + to perform sparse BLAS operations. + +.. container:: section + + .. rubric:: 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. + + | :ref:`oneapi::mkl::device_bad_alloc` + | :ref:`oneapi::mkl::host_bad_alloc` + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::unsupported_device` + +.. _onemkl_sparse_create_dense_matrix_usm: + +create_dense_matrix (USM version) +--------------------------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + template + void create_dense_matrix (sycl::queue &queue, + oneapi::mkl::sparse::dense_matrix_handle_t *p_dmhandle, + std::int64_t num_rows, + std::int64_t num_cols, + std::int64_t ld, + layout dense_layout, + fpType *val); + + } + +.. container:: section + + .. rubric:: Template parameters + + fpType + See :ref:`supported template types`. + +.. container:: section + + .. rubric:: Input parameters + + queue + The SYCL command queue which will be used for SYCL kernels execution. + + p_dmhandle + The address of the ``p_dmhandle`` object to be initialized. Must only be + called on an uninitialized ``dense_matrix_handle_t`` object. + + num_rows + Number of rows of the provided data ``val``. Must be at least 0. + + num_cols + Number of columns of the provided data ``val``. Must be at least 0. + + ld + Leading dimension of the provided data ``val``. Must be at least + ``num_rows`` if column major layout is used or at least ``num_cols`` if + row major layout is used. + + dense_layout + Specify whether the data uses row major or column major. + + val + USM pointer of length ``ld*num_cols`` if column major is used or + ``ld*num_rows`` if row major is used. Holds the data to initialize + ``p_dmhandle`` with. The data must be accessible on the device. + +.. container:: section + + .. rubric:: Output parameters + + p_dmhandle + On return, the address is updated to point to a newly allocated and + initialized ``dense_matrix_handle_t`` object that can be filled and used + to perform sparse BLAS operations. + +.. container:: section + + .. rubric:: 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. + + | :ref:`oneapi::mkl::device_bad_alloc` + | :ref:`oneapi::mkl::host_bad_alloc` + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::unsupported_device` + +**Parent topic:** :ref:`onemkl_sparse_data_handles` diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_vector.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_vector.rst new file mode 100644 index 000000000..e4d2f88a5 --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_vector.rst @@ -0,0 +1,162 @@ +.. SPDX-FileCopyrightText: 2024 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_sparse_create_dense_vector: + +create_dense_vector +=================== + +Initializes a ``dense_vector_handle_t`` object with the provided data. + +.. rubric:: Description and Assumptions + +The ``oneapi::mkl::sparse::create_dense_vector`` function initializes the +``dense_vector_handle_t`` object with the provided data. + +In the case of buffers, the reference count of the provided buffer is +incremented which extends the lifetime of the underlying buffer until the +``dvhandle`` is destroyed with ``destroy_dense_vector`` or the data is reset +with ``set_dense_vector_data``. + +In the case of USM, the object does not take ownership of the data. + +See :ref:`onemkl_sparse_dense_vector_handle`. + +.. _onemkl_sparse_create_dense_vector_buffer: + +create_dense_vector (Buffer version) +------------------------------------ + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + template + void create_dense_vector (sycl::queue &queue, + oneapi::mkl::sparse::dense_vector_handle_t *p_dvhandle, + std::int64_t size, + sycl::buffer &val); + + } + +.. container:: section + + .. rubric:: Template parameters + + fpType + See :ref:`supported template types`. + +.. container:: section + + .. rubric:: Input parameters + + queue + The SYCL command queue which will be used for SYCL kernels execution. + + p_dvhandle + The address of the ``p_dvhandle`` object to be initialized. Must only be + called on an uninitialized ``dense_vector_handle_t`` object. + + size + Number of elements of the provided data ``val``. Must be at least 0. + + val + Buffer of length ``size``. Holds the data to initialize ``p_dvhandle`` + with. + +.. container:: section + + .. rubric:: Output parameters + + p_dvhandle + On return, the address is updated to point to a newly allocated and + initialized ``dense_vector_handle_t`` object that can be filled and used + to perform sparse BLAS operations. + +.. container:: section + + .. rubric:: 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. + + | :ref:`oneapi::mkl::device_bad_alloc` + | :ref:`oneapi::mkl::host_bad_alloc` + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::unsupported_device` + +.. _onemkl_sparse_create_dense_vector_usm: + +create_dense_vector (USM version) +--------------------------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + template + void create_dense_vector (sycl::queue &queue, + oneapi::mkl::sparse::dense_vector_handle_t *p_dvhandle, + std::int64_t size, + fpType *val); + + } + +.. container:: section + + .. rubric:: Template parameters + + fpType + See :ref:`supported template types`. + +.. container:: section + + .. rubric:: Input parameters + + queue + The SYCL command queue which will be used for SYCL kernels execution. + + p_dvhandle + The address of the ``p_dvhandle`` object to be initialized. Must only be + called on an uninitialized ``dense_vector_handle_t`` object. + + size + Number of elements of the provided data ``val``. Must be at least 0. + + val + USM pointer of length ``size``. Holds the data to initialize + ``p_dvhandle`` with. The data must be accessible on the device. + +.. container:: section + + .. rubric:: Output parameters + + p_dvhandle + On return, the address is updated to point to a newly allocated and + initialized ``dense_vector_handle_t`` object that can be filled and used + to perform sparse BLAS operations. + +.. container:: section + + .. rubric:: 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. + + | :ref:`oneapi::mkl::device_bad_alloc` + | :ref:`oneapi::mkl::host_bad_alloc` + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::unsupported_device` + +**Parent topic:** :ref:`onemkl_sparse_data_handles` diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/data_handles.rst b/source/elements/oneMKL/source/domains/spblas/data_types/data_handles.rst new file mode 100644 index 000000000..57c235116 --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/data_types/data_handles.rst @@ -0,0 +1,122 @@ +.. SPDX-FileCopyrightText: 2024 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_sparse_data_handles: + +Data handles +============ + +.. _onemkl_sparse_dense_vector_handle: + +Dense vector handle +------------------- + +.. rubric:: Definition + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + struct dense_vector_handle; + using dense_vector_handle_t = dense_vector_handle*; + + } + +.. container:: section + + .. rubric:: Description + + Defines ``dense_vector_handle_t`` as an opaque pointer to the incomplete type + ``dense_vector_handle``. Each backend may provide a different + implementation of the type ``dense_vector_handle``. + + See related functions: + + - :ref:`onemkl_sparse_create_dense_vector` + - :ref:`onemkl_sparse_set_dense_vector_data` + - :ref:`onemkl_sparse_destroy_dense_vector` + +.. _onemkl_sparse_dense_matrix_handle: + +Dense matrix handle +------------------- + +.. rubric:: Definition + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + struct dense_matrix_handle; + using dense_matrix_handle_t = dense_matrix_handle*; + + } + +.. container:: section + + .. rubric:: Description + + Defines ``dense_matrix_handle_t`` as an opaque pointer to the incomplete type + ``dense_matrix_handle``. Each backend may provide a different + implementation of the type ``dense_matrix_handle``. + + See related functions: + + - :ref:`onemkl_sparse_create_dense_matrix` + - :ref:`onemkl_sparse_set_dense_matrix_data` + - :ref:`onemkl_sparse_destroy_dense_matrix` + +.. _onemkl_sparse_matrix_handle: + +Sparse matrix handle +-------------------- + +.. rubric:: Definition + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + struct matrix_handle; + using matrix_handle_t = matrix_handle*; + + } + +.. container:: section + + .. rubric:: Description + + Defines ``matrix_handle_t`` as an opaque pointer to the incomplete type + ``matrix_handle``. Each backend may provide a different + implementation of the type ``matrix_handle``. + + See related functions: + + - :ref:`onemkl_sparse_create_coo_matrix` + - :ref:`onemkl_sparse_create_csr_matrix` + - :ref:`onemkl_sparse_set_coo_matrix_data` + - :ref:`onemkl_sparse_set_csr_matrix_data` + - :ref:`onemkl_sparse_set_matrix_property` + - :ref:`onemkl_sparse_destroy_sparse_matrix` + + See a description of the supported :ref:`sparse formats`. + +.. toctree:: + :hidden: + + create_dense_vector + create_dense_matrix + create_coo_matrix + create_csr_matrix + set_dense_vector_data + set_dense_matrix_data + set_coo_matrix_data + set_csr_matrix_data + destroy_dense_vector + destroy_dense_matrix + destroy_sparse_matrix + set_matrix_property + format-descriptions + +**Parent topic:** :ref:`onemkl_spblas` diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/destroy_dense_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/destroy_dense_matrix.rst new file mode 100644 index 000000000..90ea9844c --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/data_types/destroy_dense_matrix.rst @@ -0,0 +1,55 @@ +.. SPDX-FileCopyrightText: 2024 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_sparse_destroy_dense_matrix: + +destroy_dense_matrix +==================== + +Destroys a ``dense_matrix_handle_t`` object. + +.. rubric:: Description and Assumptions + +The ``oneapi::mkl::sparse::destroy_dense_matrix`` function frees the resources +allocated for the handle. + +If a buffer was provided, its reference count is decremented. + +If a USM pointer was provided, the data is not free'd. + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + void destroy_dense_matrix (sycl::queue &queue, + oneapi::mkl::sparse::dense_matrix_handle_t dmhandle); + + } + +.. container:: section + + .. rubric:: Input parameters + + queue + The SYCL command queue which will be used for SYCL kernels execution. + + dmhandle + Handle initialized with :ref:`onemkl_sparse_create_dense_matrix`. + +.. container:: section + + .. rubric:: 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. + + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::unsupported_device` + +**Parent topic:** :ref:`onemkl_sparse_data_handles` diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/destroy_dense_vector.rst b/source/elements/oneMKL/source/domains/spblas/data_types/destroy_dense_vector.rst new file mode 100644 index 000000000..5096d9b90 --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/data_types/destroy_dense_vector.rst @@ -0,0 +1,55 @@ +.. SPDX-FileCopyrightText: 2024 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_sparse_destroy_dense_vector: + +destroy_dense_vector +==================== + +Destroys a ``dense_vector_handle_t`` object. + +.. rubric:: Description and Assumptions + +The ``oneapi::mkl::sparse::destroy_dense_vector`` function frees the resources +allocated for the handle. + +If a buffer was provided, its reference count is decremented. + +If a USM pointer was provided, the data is not free'd. + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + void destroy_dense_vector (sycl::queue &queue, + oneapi::mkl::sparse::dense_vector_handle_t dvhandle); + + } + +.. container:: section + + .. rubric:: Input parameters + + queue + The SYCL command queue which will be used for SYCL kernels execution. + + dvhandle + Handle initialized with :ref:`onemkl_sparse_create_dense_vector`. + +.. container:: section + + .. rubric:: 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. + + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::unsupported_device` + +**Parent topic:** :ref:`onemkl_sparse_data_handles` diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/destroy_sparse_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/destroy_sparse_matrix.rst new file mode 100644 index 000000000..d416d58ec --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/data_types/destroy_sparse_matrix.rst @@ -0,0 +1,55 @@ +.. SPDX-FileCopyrightText: 2024 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_sparse_destroy_sparse_matrix: + +destroy_sparse_matrix +===================== + +Destroys a ``sparse_matrix_handle_t`` object. + +.. rubric:: Description and Assumptions + +The ``oneapi::mkl::sparse::destroy_sparse_matrix`` function frees the resources +allocated for the handle. + +If a buffer was provided, its reference count is decremented. + +If a USM pointer was provided, the data is not free'd. + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + void destroy_sparse_matrix (sycl::queue &queue, + oneapi::mkl::sparse::sparse_matrix_handle_t smhandle); + + } + +.. container:: section + + .. rubric:: Input parameters + + queue + The SYCL command queue which will be used for SYCL kernels execution. + + smhandle + Handle initialized with :ref:`onemkl_sparse_create_csr_matrix` or :ref:`onemkl_sparse_create_coo_matrix`. + +.. container:: section + + .. rubric:: 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. + + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::unsupported_device` + +**Parent topic:** :ref:`onemkl_sparse_data_handles` \ No newline at end of file diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/format-descriptions.rst b/source/elements/oneMKL/source/domains/spblas/data_types/format-descriptions.rst new file mode 100644 index 000000000..9483209b9 --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/data_types/format-descriptions.rst @@ -0,0 +1,149 @@ +.. SPDX-FileCopyrightText: 2024 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_sparse_format_descriptions: + +Sparse storage formats +====================== + +There are a variety of matrix storage formats available for representing sparse +matrices. Two popular formats are the coordinate (COO) format, and the +compressed sparse row (CSR) format. + +.. container:: section + + .. _onemkl_sparse_coo: + + .. rubric:: COO + + The COO format is the simplest sparse matrix format, represented by three + arrays, ``row_ind``, ``col_ind`` and ``val``, and an ``index`` parameter. + Each non-zero element, ``i`` in the sparse matrix is represented by its row + index, column index, and value, that is, (``row_ind[i]``, ``col_ind[i]``, + ``val[i]``). The entries need not be in a sorted order. + + .. container:: tablenoborder + + .. list-table:: + + * - num_rows + - Number of rows in the sparse matrix. + * - num_cols + - Number of columns in the sparse matrix. + * - nnz + - Number of non-zero entries in the sparse matrix (which may include + explicit zeros). This is also the length of the ``row_ind``, + ``col_ind`` and ``val`` arrays. + * - index + - Parameter that is used to specify whether the matrix has zero or + one-based indexing. + * - val + - An array of length ``nnz`` that contains the non-zero elements of + the sparse matrix not necessarily in any sorted order. + * - row_ind + - An integer array of length ``nnz``. Contains row indices for + non-zero elements stored in the ``val`` array such that + ``row_ind[i]`` is the row number (using zero- or one-based + indexing) of the element of the sparse matrix stored in ``val[i]``. + * - col_ind + - An integer array of length ``nnz``. Contains column indices for + non-zero elements stored in the ``val`` array such that + ``col_ind[i]`` is the column number (using zero- or one-based + indexing) of the element of the sparse matrix stored in ``val[i]``. + +A sparse matrix can be represented in a COO format in a following way (assuming +one-based indexing): + +.. math:: + A = \left(\begin{matrix} + 1 & 0 & 2\\ + 0 & -1 & 4\\ + 3 & 0 & 0\\ + \end{matrix}\right) + ++------------+------------------------------------------------------------+ +| num_rows | 3 | ++------------+------------------------------------------------------------+ +| num_cols | 3 | ++------------+------------------------------------------------------------+ +| nnz | 5 | ++------------+------------------------------------------------------------+ +| index | 1 | ++------------+------------+-----------+-----------+-----------+-----------+ +| row_ind | 1 | 1 | 2 | 2 | 3 | ++------------+------------+-----------+-----------+-----------+-----------+ +| col_ind | 1 | 3 | 2 | 3 | 1 | ++------------+------------+-----------+-----------+-----------+-----------+ +| val | 1 | 2 | -1 | 4 | 3 | ++------------+------------+-----------+-----------+-----------+-----------+ + +.. container:: section + + .. _onemkl_sparse_csr: + + .. rubric:: CSR + + The CSR format is one of the most popular sparse matrix storage formats, + represented by three arrays, ``row_ptr``, ``col_ind`` and ``val``, and an + ``index`` parameter. + + .. container:: tablenoborder + + .. list-table:: + + * - num_rows + - Number of rows in the sparse matrix. + * - num_cols + - Number of columns in the sparse matrix. + * - nnz + - Number of non-zero entries in the sparse matrix (which may include + explicit zeros). This is also the length of the ``col_ind`` and + ``val`` arrays. + * - index + - Parameter that is used to specify whether the matrix has zero or + one-based indexing. + * - val + - An array of length ``nnz`` that contains the non-zero elements of + the sparse matrix stored row by row. + * - col_ind + - An integer array of length ``nnz``. Contains column indices for + non-zero elements stored in the ``val`` array such that + ``col_ind[i]`` is the column number (using zero- or one-based + indexing) of the element of the sparse matrix stored in ``val[i]``. + * - row_ptr + - An integer array of size equal to ``num_rows + 1``. Element ``j`` + of this integer array gives the position of the element in the + ``val`` array that is first non-zero element in a row ``j`` of + ``A``. Note that this position is equal to ``row_ptr[j] - index``. + Last element of the ``row_ptr`` array (``row_ptr[num_rows]``) + stores the sum of, number of nonzero elements and ``index`` + (``nnz + index``). + +A sparse matrix can be represented in a CSR format in a following way (assuming +zero-based indexing): + +.. math:: + A = \left(\begin{matrix} + 1 & 0 & 2\\ + 0 & -1 & 4\\ + 3 & 0 & 0\\ + \end{matrix}\right) + ++------------+------------------------------------------------------------+ +| num_rows | 3 | ++------------+------------------------------------------------------------+ +| num_cols | 3 | ++------------+------------------------------------------------------------+ +| nnz | 5 | ++------------+------------------------------------------------------------+ +| index | 0 | ++------------+------------+-----------+-----------+-----------+-----------+ +| row_ptr | 0 | 2 | 4 | 5 | | ++------------+------------+-----------+-----------+-----------+-----------+ +| col_ind | 0 | 2 | 1 | 2 | 0 | ++------------+------------+-----------+-----------+-----------+-----------+ +| val | 1 | 2 | -1 | 4 | 3 | ++------------+------------+-----------+-----------+-----------+-----------+ + +**Parent topic:** :ref:`onemkl_sparse_data_handles` diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst new file mode 100644 index 000000000..6828c7b82 --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst @@ -0,0 +1,209 @@ +.. SPDX-FileCopyrightText: 2024 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_sparse_set_coo_matrix_data: + +set_coo_matrix_data +=================== + +Reset the data of a ``matrix_handle_t`` object with the provided COO data. + +.. rubric:: Description and Assumptions + +The ``oneapi::mkl::sparse::set_coo_matrix_data`` function sets new data to the +``matrix_handle_t`` object with the provided data. + +In the case of buffers, the reference count of the provided buffer is +incremented which extends the lifetime of the underlying buffer until the +``smhandle`` is destroyed with ``destroy_sparse_matrix`` or the data is reset with +``set_coo_matrix_data``. + +In the case of USM, the object does not take ownership of the data. + +Also see :ref:`onemkl_sparse_create_coo_matrix`. + +.. _onemkl_sparse_set_coo_matrix_data_buffer: + +set_coo_matrix_data (Buffer version) +------------------------------------ + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + template + void set_coo_matrix_data (sycl::queue &queue, + oneapi::mkl::sparse::matrix_handle_t smhandle, + std::int64_t num_rows, + std::int64_t num_cols, + std::int64_t nnz, + index_base index, + sycl::buffer &row_ind, + sycl::buffer &col_ind, + sycl::buffer &val); + + } + +.. container:: section + + .. rubric:: Template parameters + + fpType + See :ref:`supported template types`. Can be + a different type than what was used when creating the ``matrix_handle_t``. + + intType + See :ref:`supported template types`. Can be + a different type than what was used when creating the ``matrix_handle_t``. + +.. container:: section + + .. rubric:: Input parameters + + queue + The SYCL command queue which will be used for SYCL kernels execution. + + smhandle + Handle already initialized with :ref:`onemkl_sparse_create_coo_matrix`. + + num_rows + Number of rows of the provided data ``val``. Must be at least 0. + + num_cols + Number of columns of the provided data ``val``. Must be at least 0. + + nnz + Number of non-zero entries in the matrix (which may include explicit + zeros). Must be at least 0. + + index + Indicates how input arrays are indexed. The possible options are described + in :ref:`onemkl_enum_index_base` enum class. + + row_ind + Buffer of length ``nnz`` containing the row indices in ``index``-based + numbering. Refer to :ref:`onemkl_sparse_coo` format for detailed + description of ``row_ind``. + + col_ind + Buffer of length ``nnz`` containing the column indices in ``index``-based + numbering. Refer to :ref:`onemkl_sparse_coo` format for detailed + description of ``col_ind``. + + val + Buffer of length ``nnz`` containing non-zero elements (and possibly + explicit zeros) of the input matrix. Refer to :ref:`onemkl_sparse_coo` + format for detailed description of ``val``. + +.. container:: section + + .. rubric:: 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. + + | :ref:`oneapi::mkl::device_bad_alloc` + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::uninitialized` + | :ref:`oneapi::mkl::unsupported_device` + +.. _onemkl_sparse_set_coo_matrix_data_usm: + +set_coo_matrix_data (USM version) +--------------------------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + template + void set_coo_matrix_data (sycl::queue &queue, + oneapi::mkl::sparse::matrix_handle_t smhandle, + std::int64_t num_rows, + std::int64_t num_cols, + std::int64_t nnz, + index_base index, + intType *row_ind, + intType *col_ind, + fpType *val); + + } + +.. container:: section + + .. rubric:: Template parameters + + fpType + See :ref:`supported template types`. Can be + a different type than what was used when creating the ``matrix_handle_t``. + + intType + See :ref:`supported template types`. Can be + a different type than what was used when creating the ``matrix_handle_t``. + +.. container:: section + + .. rubric:: Input parameters + + queue + The SYCL command queue which will be used for SYCL kernels execution. + + smhandle + Handle already initialized with :ref:`onemkl_sparse_create_coo_matrix`. + + num_rows + Number of rows of the provided data ``val``. Must be at least 0. + + num_cols + Number of columns of the provided data ``val``. Must be at least 0. + + nnz + Number of non-zero entries in the matrix (which may include explicit + zeros). Must be at least 0. + + index + Indicates how input arrays are indexed. The possible options are described + in :ref:`onemkl_enum_index_base` enum class. + + row_ind + USM pointer of length ``nnz`` containing the row indices in + ``index``-based numbering. Refer to :ref:`onemkl_sparse_coo` format for + detailed description of ``row_ind``. The data must be accessible on the + device. + + col_ind + USM pointer of length ``nnz`` containing the column indices in + ``index``-based numbering. Refer to :ref:`onemkl_sparse_coo` format for + detailed description of ``col_ind``. The data must be accessible on the + device. + + val + USM pointer of length ``nnz`` containing non-zero elements (and possibly + explicit zeros) of the input matrix. Refer to :ref:`onemkl_sparse_coo` + format for detailed description of ``val``. The data must be accessible on + the device. + +.. container:: section + + .. rubric:: 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. + + | :ref:`oneapi::mkl::device_bad_alloc` + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::uninitialized` + | :ref:`oneapi::mkl::unsupported_device` + +**Parent topic:** :ref:`onemkl_sparse_data_handles` diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst new file mode 100644 index 000000000..962a0658a --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst @@ -0,0 +1,207 @@ +.. SPDX-FileCopyrightText: 2024 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_sparse_set_csr_matrix_data: + +set_csr_matrix_data +=================== + +Reset the data of a ``matrix_handle_t`` object with the provided CSR data. + +.. rubric:: Description and Assumptions + +The ``oneapi::mkl::sparse::set_csr_matrix_data`` function sets new data to the +``matrix_handle_t`` object with the provided data. + +In the case of buffers, the reference count of the provided buffer is +incremented which extends the lifetime of the underlying buffer until the +``smhandle`` is destroyed with ``destroy_sparse_matrix`` or the data is reset with +``set_csr_matrix_data``. + +In the case of USM, the object does not take ownership of the data. + +Also see :ref:`onemkl_sparse_create_csr_matrix`. + +.. _onemkl_sparse_set_csr_matrix_data_buffer: + +set_csr_matrix_data (Buffer version) +------------------------------------ + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + template + void set_csr_matrix_data (sycl::queue &queue, + oneapi::mkl::sparse::matrix_handle_t smhandle, + std::int64_t num_rows, + std::int64_t num_cols, + std::int64_t nnz, + index_base index, + sycl::buffer &row_ptr, + sycl::buffer &col_ind, + sycl::buffer &val); + + } + +.. container:: section + + .. rubric:: Template parameters + + fpType + See :ref:`supported template types`. Can be + a different type than what was used when creating the ``matrix_handle_t``. + + intType + See :ref:`supported template types`. Can be + a different type than what was used when creating the ``matrix_handle_t``. + +.. container:: section + + .. rubric:: Input parameters + + queue + The SYCL command queue which will be used for SYCL kernels execution. + + smhandle + Handle already initialized with :ref:`onemkl_sparse_create_csr_matrix`. + + num_rows + Number of rows of the provided data ``val``. Must be at least 0. + + num_cols + Number of columns of the provided data ``val``. Must be at least 0. + + nnz + Number of non-zero entries in the matrix (which may include explicit + zeros). Must be at least 0. + + index + Indicates how input arrays are indexed. The possible options are described + in :ref:`onemkl_enum_index_base` enum class. + + row_ptr + Buffer of length ``num_rows+1``. Refer to :ref:`onemkl_sparse_csr` format + for detailed description of ``row_ptr``. + + col_ind + Buffer of length ``nnz`` containing the column indices in ``index``-based + numbering. Refer to :ref:`onemkl_sparse_csr` format for detailed + description of ``col_ind``. + + val + Buffer of length ``nnz`` containing non-zero elements (and possibly + explicit zeros) of the input matrix. Refer to :ref:`onemkl_sparse_csr` + format for detailed description of ``val``. + +.. container:: section + + .. rubric:: 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. + + | :ref:`oneapi::mkl::device_bad_alloc` + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::uninitialized` + | :ref:`oneapi::mkl::unsupported_device` + +.. _onemkl_sparse_set_csr_matrix_data_usm: + +set_csr_matrix_data (USM version) +--------------------------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + template + void set_csr_matrix_data (sycl::queue &queue, + oneapi::mkl::sparse::matrix_handle_t smhandle, + std::int64_t num_rows, + std::int64_t num_cols, + std::int64_t nnz, + index_base index, + intType *row_ptr, + intType *col_ind, + fpType *val); + + } + +.. container:: section + + .. rubric:: Template parameters + + fpType + See :ref:`supported template types`. Can be + a different type than what was used when creating the ``matrix_handle_t``. + + intType + See :ref:`supported template types`. Can be + a different type than what was used when creating the ``matrix_handle_t``. + +.. container:: section + + .. rubric:: Input parameters + + queue + The SYCL command queue which will be used for SYCL kernels execution. + + smhandle + Handle already initialized with :ref:`onemkl_sparse_create_csr_matrix`. + + num_rows + Number of rows of the provided data ``val``. Must be at least 0. + + num_cols + Number of columns of the provided data ``val``. Must be at least 0. + + nnz + Number of non-zero entries in the matrix (which may include explicit + zeros). Must be at least 0. + + index + Indicates how input arrays are indexed. The possible options are described + in :ref:`onemkl_enum_index_base` enum class. + + row_ptr + USM pointer of length ``num_rows+1``. Refer to :ref:`onemkl_sparse_csr` + format for detailed description of ``row_ptr``. The data must be + accessible on the device. + + col_ind + USM pointer of length ``nnz`` containing the column indices in + ``index``-based numbering. Refer to :ref:`onemkl_sparse_csr` format for + detailed description of ``col_ind``. The data must be accessible on the + device. + + val + USM pointer of length ``nnz`` containing non-zero elements (and possibly + explicit zeros) of the input matrix. Refer to :ref:`onemkl_sparse_csr` + format for detailed description of ``val``. The data must be accessible on + the device. + +.. container:: section + + .. rubric:: 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. + + | :ref:`oneapi::mkl::device_bad_alloc` + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::uninitialized` + | :ref:`oneapi::mkl::unsupported_device` + +**Parent topic:** :ref:`onemkl_sparse_data_handles` diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst new file mode 100644 index 000000000..526d33e1d --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst @@ -0,0 +1,176 @@ +.. SPDX-FileCopyrightText: 2024 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_sparse_set_dense_matrix_data: + +set_dense_matrix_data +===================== + +Reset the data of a ``dense_matrix_handle_t`` object. + +.. rubric:: Description and Assumptions + +The ``oneapi::mkl::sparse::set_dense_matrix_data`` function sets new data to the +``dense_matrix_handle_t`` object with the provided data. + +In the case of buffers, the reference count of the provided buffer is +incremented which extends the lifetime of the underlying buffer until the +``dmhandle`` is destroyed with ``destroy_dense_matrix`` or the data is reset +with ``set_dense_matrix_data``. + +In the case of USM, the object does not take ownership of the data. + +Also see :ref:`onemkl_sparse_create_dense_matrix`. + +.. _onemkl_sparse_set_dense_matrix_data_buffer: + +set_dense_matrix_data (Buffer version) +-------------------------------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + template + void set_dense_matrix_data (sycl::queue &queue, + oneapi::mkl::sparse::dense_matrix_handle_t dmhandle, + std::int64_t num_rows, + std::int64_t num_cols, + std::int64_t ld, + layout dense_layout, + sycl::buffer &val); + + } + +.. container:: section + + .. rubric:: Template parameters + + fpType + See :ref:`supported template types`. Can be + a different type than what was used when creating the + ``dense_matrix_handle_t``. + +.. container:: section + + .. rubric:: Input parameters + + queue + The SYCL command queue which will be used for SYCL kernels execution. + + dmhandle + Handle already initialized with :ref:`onemkl_sparse_create_dense_matrix`. + + num_rows + Number of rows of the provided data ``val``. Must be at least 0. + + num_cols + Number of columns of the provided data ``val``. Must be at least 0. + + ld + Leading dimension of the provided data ``val``. Must be at least + ``num_rows`` if column major layout is used or at least ``num_cols`` if + row major layout is used. + + dense_layout + Specify whether the data uses row major or column major. + + val + Buffer of length ``ld*num_cols`` if column major is used or + ``ld*num_rows`` if row major is used. Holds the data to initialize + ``dmhandle`` with. + +.. container:: section + + .. rubric:: 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. + + | :ref:`oneapi::mkl::device_bad_alloc` + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::uninitialized` + | :ref:`oneapi::mkl::unsupported_device` + +.. _onemkl_sparse_set_dense_matrix_data_usm: + +set_dense_matrix_data (USM version) +----------------------------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + template + void set_dense_matrix_data (sycl::queue &queue, + oneapi::mkl::sparse::dense_matrix_handle_t dmhandle, + std::int64_t num_rows, + std::int64_t num_cols, + std::int64_t ld, + layout dense_layout, + fpType *val); + + } + +.. container:: section + + .. rubric:: Template parameters + + fpType + See :ref:`supported template types`. Can be + a different type than what was used when creating the + ``dense_matrix_handle_t``. + +.. container:: section + + .. rubric:: Input parameters + + queue + The SYCL command queue which will be used for SYCL kernels execution. + + dmhandle + Handle already initialized with :ref:`onemkl_sparse_create_dense_matrix`. + + num_rows + Number of rows of the provided data ``val``. Must be at least 0. + + num_cols + Number of columns of the provided data ``val``. Must be at least 0. + + ld + Leading dimension of the provided data ``val``. Must be at least + ``num_rows`` if column major layout is used or at least ``num_cols`` if + row major layout is used. + + dense_layout + Specify whether the data uses row major or column major. + + val + USM pointer of length ``ld*num_cols`` if column major is used or + ``ld*num_rows`` if row major is used. Holds the data to initialize + ``dmhandle`` with. The data must be accessible on the device. + +.. container:: section + + .. rubric:: 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. + + | :ref:`oneapi::mkl::device_bad_alloc` + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::uninitialized` + | :ref:`oneapi::mkl::unsupported_device` + +**Parent topic:** :ref:`onemkl_sparse_data_handles` diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst new file mode 100644 index 000000000..7442c4b3d --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst @@ -0,0 +1,144 @@ +.. SPDX-FileCopyrightText: 2024 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_sparse_set_dense_vector_data: + +set_dense_vector_data +===================== + +Reset the data of a ``dense_vector_handle_t`` object. + +.. rubric:: Description and Assumptions + +The ``oneapi::mkl::sparse::set_dense_vector_data`` function sets new data to the +``dense_vector_handle_t`` object. + +In the case of buffers, the reference count of the provided buffer is +incremented which extends the lifetime of the underlying buffer until the +``dvhandle`` is destroyed with ``destroy_dense_vector`` or the data is reset +with ``set_dense_vector_data``. + +In the case of USM, the object does not take ownership of the data. + +Also see :ref:`onemkl_sparse_create_dense_vector`. + +.. _onemkl_sparse_set_dense_vector_data_buffer: + +set_dense_vector_data (Buffer version) +-------------------------------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + template + void set_dense_vector_data (sycl::queue &queue, + oneapi::mkl::sparse::dense_vector_handle_t dvhandle, + std::int64_t size, + sycl::buffer &val); + + } + +.. container:: section + + .. rubric:: Template parameters + + fpType + See :ref:`supported template types`. Can be + a different type than what was used when creating the + ``dense_vector_handle_t``. + +.. container:: section + + .. rubric:: Input parameters + + queue + The SYCL command queue which will be used for SYCL kernels execution. + + dvhandle + Handle already initialized with :ref:`onemkl_sparse_create_dense_vector`. + + size + Number of elements of the provided data ``val``. Must be at least 0. + + val + Buffer of length ``size``. + +.. container:: section + + .. rubric:: 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. + + | :ref:`oneapi::mkl::device_bad_alloc` + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::uninitialized` + | :ref:`oneapi::mkl::unsupported_device` + +.. _onemkl_sparse_set_dense_vector_data_usm: + +set_dense_vector_data (USM version) +----------------------------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + template + void set_dense_vector_data (sycl::queue &queue, + oneapi::mkl::sparse::dense_vector_handle_t dvhandle, + std::int64_t size, + fpType *val); + + } + +.. container:: section + + .. rubric:: Template parameters + + fpType + See :ref:`supported template types`. Can be + a different type than what was used when creating the + ``dense_vector_handle_t``. + +.. container:: section + + .. rubric:: Input parameters + + queue + The SYCL command queue which will be used for SYCL kernels execution. + + dvhandle + Handle already initialized with :ref:`onemkl_sparse_create_dense_vector`. + + size + Number of elements of the provided data ``val``. Must be at least 0. + + val + USM pointer of length ``size``. The data must be accessible on the device. + +.. container:: section + + .. rubric:: 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. + + | :ref:`oneapi::mkl::device_bad_alloc` + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::uninitialized` + | :ref:`oneapi::mkl::unsupported_device` + +**Parent topic:** :ref:`onemkl_sparse_data_handles` diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_property.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_property.rst new file mode 100644 index 000000000..ee5893fe5 --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_property.rst @@ -0,0 +1,95 @@ +.. SPDX-FileCopyrightText: 2024 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_sparse_set_matrix_property: + +set_matrix_property +=================== + +Matrix properties +----------------- + +.. container:: section + + .. code:: cpp + + enum class matrix_property { + symmetric, + sorted, + }; + + TODO: Clarify are the properties meant to be used as a bit mask so multiple + properties can be set? + + .. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - Value + - Description + * - ``symmetric`` + - Guarantees that the matrix is symmetric, meaning it must be square and + its transpose is equal to itself. TODO: Confirm whether the user can + only provide half of the data in this case? + * - ``sorted`` + - Guarantees that the column indices are sorted for a given row. Only + available for the CSR format. TODO: Confirm the description. + +set_matrix_property +------------------- + +Set a property to a ``sparse_matrix_handle_t`` object. + +.. rubric:: Description and Assumptions + +The ``oneapi::mkl::sparse::set_matrix_property`` function sets a property to a +matrix handle. The property provides stronger guarantees than a :ref:`onemkl_sparse_matrix_view`. + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + bool set_matrix_property (sycl::queue &queue, + oneapi::mkl::sparse::sparse_matrix_handle_t smhandle, + matrix_property property_value); + + } + +.. container:: section + + .. rubric:: Input parameters + + queue + The SYCL command queue which will be used for SYCL kernels execution. + + smhandle + Initialized sparse matrix handle. + + property_value + Matrix property to set. + +.. container:: section + + .. rubric:: Return Values + + Return whether the property was set to the backend's handle. A backend may + not have equivalent properties. + +.. container:: section + + .. rubric:: 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. + + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::uninitialized` + | :ref:`oneapi::mkl::unsupported_device` + +**Parent topic:** :ref:`onemkl_sparse_data_handles` diff --git a/source/elements/oneMKL/source/domains/spblas/format-descriptions.rst b/source/elements/oneMKL/source/domains/spblas/format-descriptions.rst deleted file mode 100644 index 6815ad61b..000000000 --- a/source/elements/oneMKL/source/domains/spblas/format-descriptions.rst +++ /dev/null @@ -1,154 +0,0 @@ -.. SPDX-FileCopyrightText: 2019-2024 Intel Corporation -.. -.. SPDX-License-Identifier: CC-BY-4.0 - -.. _onemkl_sparse_format_descriptions: - -Sparse storage formats -====================== - -There are a variety of matrix storage formats available for -representing sparse matrices. Two popular formats are the -coordinate (COO) format, and the compressed sparse row (CSR) -format. - -.. container:: section - - .. _onemkl_sparse_coo: - - .. rubric:: COO - - The COO format is the simplest sparse matrix format, - represented by three arrays, *row_ind*, *col_ind* - and *val*, and an *index* parameter. Each non-zero - element, *i* in the sparse matrix is represented by its - row index, column index, and value, that is, - *(row_ind[i], col_ind[i], val[i])*. The entries need not - be in a sorted order. - - .. container:: tablenoborder - - .. list-table:: - - * - nrows - - Number of rows in the sparse matrix. - * - ncols - - Number of columns in the sparse matrix. - * - nnz - - Number of non-zero entries in the sparse matrix (which may include explicit zeros). - This is also the length of the *row_ind*, *col_ind* and *val* arrays. - * - index - - Parameter that is used to specify whether the matrix has zero or one-based indexing. - * - val - - An array of length ``nnz`` that contains the non-zero elements of the sparse matrix - not necessarily in any sorted order. - * - row_ind - - An integer array of length ``nnz``. Contains row indices for non-zero elements - stored in the *val* array such that *row_ind[i]* is the row number (using zero- - or one-based indexing) of the element of the sparse matrix stored in *val[i]*. - * - col_ind - - An integer array of length ``nnz``. Contains column indices for non-zero elements - stored in the *val* array such that *col_ind[i]* is the column number (using zero- - or one-based indexing) of the element of the sparse matrix stored in *val[i]*. - - -A sparse matrix can be represented in a COO format in a following way (assuming one-based indexing): - -.. math:: - A = \left(\begin{matrix} - 1 & 0 & 2\\ - 0 & -1 & 4\\ - 3 & 0 & 0\\ - \end{matrix}\right) - - -+------------+------------------------------------------------------------+ -| nrows | 3 | -+------------+------------------------------------------------------------+ -| ncols | 3 | -+------------+------------------------------------------------------------+ -| nnz | 5 | -+------------+------------------------------------------------------------+ -| index | 1 | -+------------+------------+-----------+-----------+-----------+-----------+ -| row_ind | 1 | 1 | 2 | 2 | 3 | -+------------+------------+-----------+-----------+-----------+-----------+ -| col_ind | 1 | 3 | 2 | 3 | 1 | -+------------+------------+-----------+-----------+-----------+-----------+ -| val | 1 | 2 | -1 | 4 | 3 | -+------------+------------+-----------+-----------+-----------+-----------+ - - -.. container:: section - - .. _onemkl_sparse_csr: - - .. rubric:: CSR - - The CSR format is one of the most popular sparse matrix - storage formats, represented by three arrays, - *row_ptr*, *col_ind* and *val*, and an *index* - parameter. - - .. container:: tablenoborder - - .. list-table:: - - * - nrows - - Number of rows in the sparse matrix. - * - ncols - - Number of columns in the sparse matrix. - * - nnz - - Number of non-zero entries in the sparse matrix (which may include explicit zeros). - This is also the length of the *col_ind* and *val* arrays. - * - index - - Parameter that is used to specify whether the matrix has zero or one-based indexing. - * - val - - An array of length ``nnz`` that contains the non-zero elements of the sparse matrix - stored row by row. - * - col_ind - - An integer array of length ``nnz``. Contains column indices for non-zero elements - stored in the *val* array such that *col_ind[i]* is the column number (using zero- - or one-based indexing) of the element of the sparse matrix stored in *val[i]*. - * - row_ptr - - An integer array of size equal to ``nrows + 1``. Element j of this integer array - gives the position of the element in the *val* array that is first non-zero element in a - row j of A. Note that this position is equal to *row_ptr[j] - index*. Last element of - the *row_ptr* array (*row_ptr[nrows]*) stores the sum of, - number of nonzero elements and *index* (*nnz* + *index*). - - -A sparse matrix can be represented in a CSR format in a following way (assuming zero-based indexing): - -.. math:: - A = \left(\begin{matrix} - 1 & 0 & 2\\ - 0 & -1 & 4\\ - 3 & 0 & 0\\ - \end{matrix}\right) - - -+------------+------------------------------------------------------------+ -| nrows | 3 | -+------------+------------------------------------------------------------+ -| ncols | 3 | -+------------+------------------------------------------------------------+ -| nnz | 5 | -+------------+------------------------------------------------------------+ -| index | 0 | -+------------+------------+-----------+-----------+-----------+-----------+ -| row_ptr | 0 | 2 | 4 | 5 | | -+------------+------------+-----------+-----------+-----------+-----------+ -| col_ind | 0 | 2 | 1 | 2 | 0 | -+------------+------------+-----------+-----------+-----------+-----------+ -| val | 1 | 2 | -1 | 4 | 3 | -+------------+------------+-----------+-----------+-----------+-----------+ - - -.. container:: familylinks - - - .. container:: parentlink - - - **Parent topic:** :ref:`onemkl_spblas` diff --git a/source/elements/oneMKL/source/domains/spblas/gemm.rst b/source/elements/oneMKL/source/domains/spblas/gemm.rst deleted file mode 100644 index bcc2bed6f..000000000 --- a/source/elements/oneMKL/source/domains/spblas/gemm.rst +++ /dev/null @@ -1,335 +0,0 @@ -.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation -.. -.. SPDX-License-Identifier: CC-BY-4.0 - -.. _onemkl_sparse_gemm: - -gemm -==== - -Computes a sparse matrix times dense matrix product. - -.. rubric:: Description and Assumptions - -Refer to :ref:`onemkl_sparse_supported_types` for a list of supported ```` and ```` types. The oneapi::mkl::sparse::gemm routine computes a sparse matrix-dense -matrix product defined as - -.. math:: - - C \leftarrow \alpha \cdot \text{op}(A) \cdot \text{op}(B) + \beta \cdot C - -where :math:`\alpha` and :math:`\beta` are scalars, :math:`A` is a sparse matrix, :math:`B` and :math:`C` are dense matrices, :math:`\text{op}()` is a matrix modifier for :math:`A` and :math:`B` using the following description: - -.. math:: - - \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} - - -and :math:`\text{op}(A)` is an ``m``-by-``k`` matrix , :math:`\text{op}(B)` is an ``k``-by-``columns`` matrix, and :math:`C` is an ``m``-by-``columns`` matrix. - -Dense matrix storage is in either row-major or column-major format. Sparse matrix formats are compressed sparse row (CSR) or coordinate (COO) formats. - - -.. _onemkl_sparse_gemm_buffer: - -gemm (Buffer version) ---------------------- - -.. rubric:: Syntax - -.. code-block:: cpp - - namespace oneapi::mkl::sparse { - - void gemm (sycl::queue &queue, - oneapi::mkl::layout dense_matrix_layout, - oneapi::mkl::transpose transpose_A, - oneapi::mkl::transpose transpose_B, - const fp alpha, - oneapi::mkl::sparse::matrix_handle_t A_handle, - sycl::buffer &B, - const std::int64_t columns, - const std::int64_t ldb, - const fp beta, - sycl::buffer &C, - const std::int64_t ldc); - - } - - - -.. container:: section - - .. rubric:: Input parameters - - queue - Specifies the SYCL command queue which will be used for SYCL - kernels execution. - - - dense_matrix_layout - Specifies the storage scheme in memory for the dense matrices. Note that this layout applies to both :math:`B` and :math:`C` dense matrices. - The possible options are described in :ref:`onemkl_enum_layout` enum class. - - - transpose_A - Specifies operation ``op()`` on input matrix :math:`A`. The possible options - are described in :ref:`onemkl_enum_transpose` enum class. - - - transpose_B - Specifies operation ``op()`` on input matrix :math:`B`. The possible options - are described in :ref:`onemkl_enum_transpose` enum class. - - - alpha - Specifies the scalar :math:`\alpha`. - - - A_handle - Handle to object containing sparse matrix, :math:`A`. Created using - one of ``oneapi::mkl::sparse::set_csr_data`` or - ``oneapi::mkl::sparse::set_coo_data`` routines. - - - B - The input dense matrix :math:`B` in the sparse matrix-dense matrix product. :math:`B` is a one dimensional SYCL memory object containing an array of size: - - .. list-table:: - :header-rows: 1 - - * - - - ``B`` not transposed - - ``B`` transposed - * - Row major - - ``B`` is an ``k``-by-``columns`` matrix so must have size at least ``k``\ \*\ ``ldb``. - - ``B`` is an ``columns``-by-``k`` matrix so must have size at least ``columns``\ \*\ ``ldb`` - * - Column major - - ``B`` is an ``k``-by-``columns`` matrix so must have size at least ``ldb``\ \*\ ``columns``. - - ``B`` is an ``columns``-by-``k`` matrix so must have size at least ``ldb``\ \*\ ``k`` - - See :ref:`matrix-storage` for more details. - - - columns - Number of columns of matrix :math:`C`. - - - ldb - Specifies the leading dimension of matrix :math:`B`. It must be positive. - - .. list-table:: - :header-rows: 1 - - * - - - ``B`` not transposed - - ``B`` transposed - * - Row major - - ``ldb`` must be at least ``columns``. - - ``ldb`` must be at least ``k``. - * - Column major - - ``ldb`` must be at least ``k``. - - ``ldb`` must be at least ``columns``. - - - beta - Specifies the scalar ``beta``. - - - C - The dense matrix input/output array. A one-dimensional SYCL memory object containing an array of size at least ``m``\ \*\ ``ldc`` if row_major layout is used to store dense matrices - or at least ``ldc``\ \*\ ``columns`` if column_major layout is used to store dense matrices. - - - ldc - Specifies the leading dimension of matrix :math:`C`. - Must be positive and at least ``columns`` if row major layout is used to store dense matrices or at least ``m`` if column major layout is used to store dense matrices. - - -.. container:: section - - .. rubric:: Output Parameters - :class: sectiontitle - - - C - Dense matrix output is overwritten by the updated matrix, :math:`C`. - -.. container:: section - - .. rubric:: Throws - :class: sectiontitle - - This routine 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. - - | :ref:`oneapi::mkl::computation_error` - | :ref:`oneapi::mkl::device_bad_alloc` - | :ref:`oneapi::mkl::host_bad_alloc` - | :ref:`oneapi::mkl::invalid_argument` - | :ref:`oneapi::mkl::unimplemented` - | :ref:`oneapi::mkl::uninitialized` - | :ref:`oneapi::mkl::unsupported_device` - -.. _onemkl_sparse_gemm_usm: - -gemm (USM version) ---------------------- - -.. rubric:: Syntax - -.. code-block:: cpp - - namespace oneapi::mkl::sparse { - - sycl::event gemm (sycl::queue &queue, - oneapi::mkl::layout dense_matrix_layout, - oneapi::mkl::transpose transpose_A, - oneapi::mkl::transpose transpose_B, - const fp alpha, - oneapi::mkl::sparse::matrix_handle_t A_handle, - const fp *B, - const std::int64_t columns, - const std::int64_t ldb, - const fp beta, - fp *C, - const std::int64_t ldc, - const std::vector &dependencies = {}); - - } - - -.. container:: section - - .. rubric:: Input parameters - - queue - Specifies the SYCL command queue which will be used for SYCL - kernels execution. - - - dense_matrix_layout - Specifies the storage scheme in memory for the dense matrices. Note that this layout applies to both :math:`B` and :math:`C` dense matrices. - The possible options are described in :ref:`onemkl_enum_layout` enum class. - - - transpose_A - Specifies operation ``op()`` on input matrix :math:`A`. The possible options - are described in :ref:`onemkl_enum_transpose` enum class. - - - transpose_B - Specifies operation ``op()`` on input matrix :math:`B`. The possible options - are described in :ref:`onemkl_enum_transpose` enum class. - - - alpha - Specifies the scalar :math:`\alpha`. - - - A_handle - Handle to object containing sparse matrix, :math:`A`. Created using - one of ``oneapi::mkl::sparse::set_csr_data`` or - ``oneapi::mkl::sparse::set_coo_data`` routines. - - - B - The input dense matrix :math:`B` in the sparse matrix-dense matrix product. :math:`B` is a device accessible one-dimensional USM object containing an array of size: - - .. list-table:: - :header-rows: 1 - - * - - - ``B`` not transposed - - ``B`` transposed - * - Row major - - ``B`` is an ``k``-by-``columns`` matrix so must have size at least ``k``\ \*\ ``ldb``. - - ``B`` is an ``columns``-by-``k`` matrix so must have size at least ``columns``\ \*\ ``ldb`` - * - Column major - - ``B`` is an ``k``-by-``columns`` matrix so must have size at least ``ldb``\ \*\ ``columns``. - - ``B`` is an ``columns``-by-``k`` matrix so must have size at least ``ldb``\ \*\ ``k`` - - See :ref:`matrix-storage` for more details. - - - columns - Number of columns of matrix :math:`C`. - - - ldb - Specifies the leading dimension of matrix :math:`B`. It must be positive. - - .. list-table:: - :header-rows: 1 - - * - - - ``B`` not transposed - - ``B`` transposed - * - Row major - - ``ldb`` must be at least ``columns``. - - ``ldb`` must be at least ``k``. - * - Column major - - ``ldb`` must be at least ``k``. - - ``ldb`` must be at least ``columns``. - - - beta - Specifies the scalar ``beta``. - - - C - The dense matrix input/output array. A device accessible USM object containing an array of size at least ``m``\ \*\ ``ldc`` if row_major layout is used to store dense matrices - or at least ``ldc``\ \*\ ``columns`` if column_major layout is used to store dense matrices. - - ldc - Specifies the leading dimension of matrix :math:`C`. - Must be positive and at least ``columns`` if row major layout is used to store dense matrices or at least ``m`` if column major layout is used to store dense matrices. - - dependencies - List of events that oneapi::mkl::sparse::gemm routine depends on. - If omitted, defaults to no dependencies. - -.. container:: section - - .. rubric:: Output Parameters - :class: sectiontitle - - - C - Dense matrix output is overwritten by the updated matrix :math:`C`. - - -.. container:: section - - .. rubric:: Throws - :class: sectiontitle - - This routine 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. - - | :ref:`oneapi::mkl::computation_error` - | :ref:`oneapi::mkl::device_bad_alloc` - | :ref:`oneapi::mkl::host_bad_alloc` - | :ref:`oneapi::mkl::invalid_argument` - | :ref:`oneapi::mkl::unimplemented` - | :ref:`oneapi::mkl::uninitialized` - | :ref:`oneapi::mkl::unsupported_device` - -.. container:: section - - .. rubric:: Return Values - :class: sectiontitle - - Output event that can be waited upon or added as a - dependency for the completion of gemm routine. - - -.. container:: familylinks - - - .. container:: parentlink - - - **Parent topic:** :ref:`onemkl_spblas` diff --git a/source/elements/oneMKL/source/domains/spblas/gemmoptimize.rst b/source/elements/oneMKL/source/domains/spblas/gemmoptimize.rst deleted file mode 100644 index 235eff332..000000000 --- a/source/elements/oneMKL/source/domains/spblas/gemmoptimize.rst +++ /dev/null @@ -1,208 +0,0 @@ -.. SPDX-FileCopyrightText: 2023 Intel Corporation -.. -.. SPDX-License-Identifier: CC-BY-4.0 - -.. _onemkl_sparse_optimize_gemm: - -optimize_gemm -============= - -Performs internal optimizations for oneapi::mkl::sparse::gemm by analyzing -the matrix structure. - -.. rubric:: Description and Assumptions - -The oneapi::mkl::sparse::optimize_gemm routine analyzes matrix structure -and performs optimizations. Optimized data is then stored in -the handle. - -In contrast to other optimization routines in Sparse BLAS domain -which are done solely based on the sparse matrix pattern, -two versions of the ``sparse::optimize_gemm`` routine are provided for preparing different -optimizations for ``sparse::gemm`` routine. In particular, if the shape -of the dense matrix right hand side, :math:`B`, is unknown or widely varying in -subsequent calls to ``sparse::gemm`` then a user might reasonably -only wish to perform optimizations for ``:sparse::gemm`` with respect -to the sparse matrix structure. However, if one or more particular shapes of :math:`B` -is available, then each :math:`B` shape can be provided as an additional hint -along with the sparse matrix pattern in the call to ``sparse::optimize_gemm``. This -second version of the API with :math:`B` shape should be callable one or -more times and may allow libraries to provide more targeted performance -optimizations. - -.. _onemkl_sparse_optimize_gemm_A: - -optimize_gemm (based on Sparse Matrix) --------------------------------------- - -.. rubric:: Syntax - -.. code-block:: cpp - - namespace oneapi::mkl::sparse { - - sycl::event optimize_gemm (sycl::queue &queue, - oneapi::mkl::transpose transpose_A, - oneapi::mkl::sparse::matrix_handle_t A_handle, - const std::vector &dependencies = {}); - - } - -.. container:: section - - .. rubric:: Input Parameters - - queue - Specifies the SYCL command queue which will be used for SYCL - kernels execution. - - - transpose_A - Specifies operation ``op()`` on input matrix :math:`A`. The possible options - are described in :ref:`onemkl_enum_transpose` enum class. - - - A_handle - Handle to object containing sparse matrix and other internal - data. Created using one of ``oneapi::mkl::sparse::set_csr_data`` or - ``oneapi::mkl::sparse::set_coo_data`` routines. - - - dependencies - List of events that oneapi::mkl::sparse::optimize_gemm routine depends on. - - -.. container:: section - - .. rubric:: Output Parameters - :class: sectiontitle - - handle - Handle might be updated with some internal optimized data by this routine. - -.. container:: section - - .. rubric:: Throws - :class: sectiontitle - - This routine 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. - - | :ref:`oneapi::mkl::computation_error` - | :ref:`oneapi::mkl::device_bad_alloc` - | :ref:`oneapi::mkl::host_bad_alloc` - | :ref:`oneapi::mkl::invalid_argument` - | :ref:`oneapi::mkl::unimplemented` - | :ref:`oneapi::mkl::uninitialized` - | :ref:`oneapi::mkl::unsupported_device` - -.. container:: section - - .. rubric:: Return Values - :class: sectiontitle - - Output event that can be waited upon or added as a - dependency for the completion of optimize_gemm routine. - - -.. _onemkl_sparse_optimize_gemm_AB: - -optimize_gemm (based on Both Input Matrices) --------------------------------------------- - -.. rubric:: Syntax - -.. code-block:: cpp - - namespace oneapi::mkl::sparse { - - sycl::event optimize_gemm (sycl::queue &queue, - oneapi::mkl::transpose transpose_A, - oneapi::mkl::transpose transpose_B, - oneapi::mkl::layout dense_matrix_layout, - const std::int64_t columns, - oneapi::mkl::sparse::matrix_handle_t A_handle, - const std::vector &dependencies = {}); - - } - -.. container:: section - - .. rubric:: Input Parameters - - queue - Specifies the SYCL command queue which will be used for SYCL - kernels execution. - - - transpose_A - Specifies operation ``op()`` on input matrix :math:`A`. The possible options - are described in :ref:`onemkl_enum_transpose` enum class. - - - transpose_B - Specifies operation ``op()`` on input matrix :math:`B`. The possible options - are described in :ref:`onemkl_enum_transpose` enum class. - - - dense_matrix_layout - Specifies the storage scheme in memory for the dense matrices. Note that this layout applies to both :math:`B` and :math:`C` dense matrices. - The possible options are described in :ref:`onemkl_enum_layout` enum class. - - - columns - Number of columns of matrix :math:`C`. - - - handle - Handle to object containing sparse matrix and other internal - data. Created using one of ``oneapi::mkl::sparse::set_csr_data`` or - ``oneapi::mkl::sparse::set_coo_data`` routines. - - - dependencies - List of events that oneapi::mkl::sparse::optimize_gemm routine depends on. - - -.. container:: section - - .. rubric:: Output Parameters - :class: sectiontitle - - handle - Handle might be updated with some internal optimized data by this routine. - -.. container:: section - - .. rubric:: Throws - :class: sectiontitle - - This routine 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. - - | :ref:`oneapi::mkl::computation_error` - | :ref:`oneapi::mkl::device_bad_alloc` - | :ref:`oneapi::mkl::host_bad_alloc` - | :ref:`oneapi::mkl::invalid_argument` - | :ref:`oneapi::mkl::unimplemented` - | :ref:`oneapi::mkl::uninitialized` - | :ref:`oneapi::mkl::unsupported_device` - -.. container:: section - - .. rubric:: Return Values - :class: sectiontitle - - Output event that can be waited upon or added as a - dependency for the completion of optimize_gemm routine. - - -.. container:: familylinks - - - .. container:: parentlink - - - **Parent topic:** :ref:`onemkl_spblas` diff --git a/source/elements/oneMKL/source/domains/spblas/gemv.rst b/source/elements/oneMKL/source/domains/spblas/gemv.rst deleted file mode 100644 index 48842583e..000000000 --- a/source/elements/oneMKL/source/domains/spblas/gemv.rst +++ /dev/null @@ -1,218 +0,0 @@ -.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation -.. -.. SPDX-License-Identifier: CC-BY-4.0 - -.. _onemkl_sparse_gemv: - -gemv -==== - - -Computes a sparse matrix-dense vector product. - -.. rubric:: Description and Assumptions - -Refer to :ref:`onemkl_sparse_supported_types` for a -list of supported ```` and ````. -The oneapi::mkl::sparse::gemv routine computes a sparse matrix-dense vector -product defined as - -.. math:: - - y \leftarrow \alpha \text{op}(A) x + \beta y - -where :math:`\alpha` and :math:`\beta` are scalars, :math:`x` and :math:`y` are dense vectors, ``A`` is a sparse matrix. - - -.. _onemkl_sparse_gemv_buffer: - -gemv (Buffer version) ---------------------- - -.. rubric:: Syntax - -.. code-block:: cpp - - namespace oneapi::mkl::sparse { - - void gemv (sycl::queue &queue, - oneapi::mkl::transpose transpose_val, - const fp alpha, - oneapi::mkl::sparse::matrix_handle_t A_handle, - sycl::buffer &x, - const fp beta, - sycl::buffer &y); - - } - - -.. container:: section - - .. rubric:: Input Parameters - - queue - Specifies the SYCL command queue which will be used for SYCL - kernels execution. - - - transpose_val - Specifies operation ``op()`` on input matrix. The possible options - are described in :ref:`onemkl_enum_transpose` enum class. - - - alpha - Specifies the scalar :math:`\alpha`. - - - A_handle - Handle to object containing sparse matrix, :math:`A`. Created using - one of ``oneapi::mkl::sparse::set_csr_data`` or - ``oneapi::mkl::sparse::set_coo_data`` routines. - - - x - SYCL memory object containing an array of size at least - equal to the number of columns of matrix :math:`\text{op}(A)`. - - - beta - Specifies the scalar :math:`\beta`. - - - y - SYCL memory object containing an array of size at least - equal to the number of rows of matrix :math:`\text{op}(A)`. - -.. container:: section - - .. rubric:: Output Parameters - :class: sectiontitle - - y - Overwritten by the updated vector ``y``. - - -.. container:: section - - .. rubric:: Throws - :class: sectiontitle - - This routine 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. - - | :ref:`oneapi::mkl::computation_error` - | :ref:`oneapi::mkl::device_bad_alloc` - | :ref:`oneapi::mkl::host_bad_alloc` - | :ref:`oneapi::mkl::invalid_argument` - | :ref:`oneapi::mkl::unimplemented` - | :ref:`oneapi::mkl::uninitialized` - | :ref:`oneapi::mkl::unsupported_device` - -.. _onemkl_sparse_gemv_usm: - -gemv (USM version) ------------------- - -.. rubric:: Syntax - - -.. code-block:: cpp - - namespace oneapi::mkl::sparse { - - sycl::event gemv (sycl::queue &queue, - oneapi::mkl::transpose transpose_val, - const fp alpha, - oneapi::mkl::sparse::matrix_handle_t A_handle, - const fp *x, - const fp beta, - fp *y, - const std::vector &dependencies = {}); - - } - - -.. container:: section - - .. rubric:: Input Parameters - - queue - Specifies the SYCL command queue which will be used for SYCL - kernels execution. - - - transpose_val - Specifies operation ``op()`` on input matrix. The possible options - are described in :ref:`onemkl_enum_transpose` enum class. - - - alpha - Specifies the scalar :math:`\alpha`. - - - A_handle - Handle to object containing sparse matrix, :math:`A`. Created using - one of ``oneapi::mkl::sparse::set_csr_data`` or - ``oneapi::mkl::sparse::set_coo_data`` routines. - - - x - Device-accessible USM object containing an array of size at least - equal to the number of columns of matrix :math:`\text{op}(A)`. - - - beta - Specifies the scalar :math:`\beta`. - - - y - Device-accessible USM object containing an array of size at least - equal to the number of rows of matrix :math:`\text{op}(A)`. - - - dependencies - List of events that oneapi::mkl::sparse::gemv routine depends on. - If omitted, defaults to no dependencies. - -.. container:: section - - .. rubric:: Output Parameters - :class: sectiontitle - - y - Overwritten by the updated vector ``y``. - -.. container:: section - - .. rubric:: Throws - :class: sectiontitle - - This routine 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. - - | :ref:`oneapi::mkl::computation_error` - | :ref:`oneapi::mkl::device_bad_alloc` - | :ref:`oneapi::mkl::host_bad_alloc` - | :ref:`oneapi::mkl::invalid_argument` - | :ref:`oneapi::mkl::unimplemented` - | :ref:`oneapi::mkl::uninitialized` - | :ref:`oneapi::mkl::unsupported_device` - -.. container:: section - - .. rubric:: Return Values - :class: sectiontitle - - Output event that can be waited upon or added as a - dependency for the completion of gemv routine. - - -.. container:: familylinks - - - .. container:: parentlink - - - **Parent topic:** :ref:`onemkl_spblas` diff --git a/source/elements/oneMKL/source/domains/spblas/gemvdot.rst b/source/elements/oneMKL/source/domains/spblas/gemvdot.rst deleted file mode 100644 index b615e3bae..000000000 --- a/source/elements/oneMKL/source/domains/spblas/gemvdot.rst +++ /dev/null @@ -1,237 +0,0 @@ -.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation -.. -.. SPDX-License-Identifier: CC-BY-4.0 - -.. _onemkl_sparse_gemvdot: - -gemvdot -======= - -Computes a sparse matrix-dense vector product with dot product. - -.. rubric:: Description and Assumptions - -Refer to :ref:`onemkl_sparse_supported_types` for a -list of supported ```` and ````. -The oneapi::mkl::sparse::gemvdot routine computes a sparse -matrix-dense vector product and dot product defined as - - -.. math:: - - y \leftarrow \alpha \text{op}(A) x + \beta y - - -.. math:: - - d \leftarrow x y - -where: - - -``A`` is a general sparse matrix, :math:`\alpha`, :math:`\beta`, and -``d`` are scalars, :math:`x` and :math:`y` are dense vectors. - -.. _onemkl_sparse_gemvdot_buffer: - -gemvdot (Buffer version) ------------------------- - -.. rubric:: Syntax - -.. code-block:: cpp - - namespace oneapi::mkl::sparse { - - void gemvdot (sycl::queue &queue, - oneapi::mkl::transpose transpose_val, - const fp alpha, - oneapi::mkl::sparse::matrix_handle_t A_handle, - sycl::buffer &x, - const fp beta, - sycl::buffer &y, - sycl::buffer &d); - - } - - -.. container:: section - - .. rubric:: Input Parameters - - queue - Specifies the SYCL command queue which will be used for SYCL - kernels execution. - - - transpose_val - Specifies operation ``op()`` on input matrix. The possible options - are described in :ref:`onemkl_enum_transpose` enum class. - - - alpha - Specifies the scalar :math:`\alpha`. - - - A_handle - Handle to object containing sparse matrix, :math:`A`. Created using - one of ``oneapi::mkl::sparse::set_csr_data`` or - ``oneapi::mkl::sparse::set_coo_data`` routines. - - - x - SYCL memory object containing an array of size at least - equal to the number of columns of matrix :math:`\text{op}(A)`. - - - beta - Specifies the scalar :math:`\beta`. - - - y - SYCL memory object containing an array of size at least - equal to the number of rows of matrix :math:`\text{op}(A)`. - - d - SYCL scalar memory object used to store the result of dot product. - -.. container:: section - - .. rubric:: Output Parameters - :class: sectiontitle - - y - Overwritten by the updated vector ``y``. - - d - Overwritten by the dot product of ``x`` and ``y``. - -.. container:: section - - .. rubric:: Throws - :class: sectiontitle - - This routine 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. - - | :ref:`oneapi::mkl::computation_error` - | :ref:`oneapi::mkl::device_bad_alloc` - | :ref:`oneapi::mkl::host_bad_alloc` - | :ref:`oneapi::mkl::invalid_argument` - | :ref:`oneapi::mkl::unimplemented` - | :ref:`oneapi::mkl::uninitialized` - | :ref:`oneapi::mkl::unsupported_device` - -.. _onemkl_sparse_gemvdot_usm: - -gemvdot (USM version) ------------------------- - -.. rubric:: Syntax - -.. code-block:: cpp - - namespace oneapi::mkl::sparse { - - sycl::event gemvdot (sycl::queue &queue, - oneapi::mkl::transpose transpose_val, - const fp alpha, - oneapi::mkl::sparse::matrix_handle_t A_handle, - const fp *x, - const fp beta, - fp *y, - fp *d, - const std::vector &dependencies = {}); - - } - -.. container:: section - - .. rubric:: Input Parameters - - queue - Specifies the SYCL command queue which will be used for SYCL - kernels execution. - - - transpose_val - Specifies operation ``op()`` on input matrix. The possible options - are described in :ref:`onemkl_enum_transpose` enum class. - - - alpha - Specifies the scalar :math:`\alpha`. - - - A_handle - Handle to object containing sparse matrix, :math:`A`. Created using - one of ``oneapi::mkl::sparse::set_csr_data`` or - ``oneapi::mkl::sparse::set_coo_data`` routines. - - - x - Device-accessible USM object containing an array of size at least - equal to the number of columns of matrix :math:`\text{op}(A)`. - - - beta - Specifies the scalar :math:`\beta`. - - - y - Device-accessible USM object containing an array of size at least - equal to the number of rows of matrix :math:`\text{op}(A)` - - d - Device-accessible USM scalar object used to store the result of dot product. - - dependencies - List of events that oneapi::mkl::sparse::gemvdot routine depends on. - If omitted, defaults to no dependencies. - -.. container:: section - - .. rubric:: Output Parameters - :class: sectiontitle - - y - Overwritten by the updated vector ``y``. - - d - Overwritten by the dot product of ``x`` and ``y``. - -.. container:: section - - .. rubric:: Throws - :class: sectiontitle - - This routine 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. - - | :ref:`oneapi::mkl::computation_error` - | :ref:`oneapi::mkl::device_bad_alloc` - | :ref:`oneapi::mkl::host_bad_alloc` - | :ref:`oneapi::mkl::invalid_argument` - | :ref:`oneapi::mkl::unimplemented` - | :ref:`oneapi::mkl::uninitialized` - | :ref:`oneapi::mkl::unsupported_device` - -.. container:: section - - .. rubric:: Return Values - :class: sectiontitle - - Output event that can be waited upon or added as a - dependency for the completion of gemvdot routine. - - -.. container:: familylinks - - - .. container:: parentlink - - - **Parent topic:** :ref:`onemkl_spblas` - diff --git a/source/elements/oneMKL/source/domains/spblas/gemvoptimize.rst b/source/elements/oneMKL/source/domains/spblas/gemvoptimize.rst deleted file mode 100644 index 4e0b6c573..000000000 --- a/source/elements/oneMKL/source/domains/spblas/gemvoptimize.rst +++ /dev/null @@ -1,96 +0,0 @@ -.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation -.. -.. SPDX-License-Identifier: CC-BY-4.0 - -.. _onemkl_sparse_optimize_gemv: - -optimize_gemv -============= - -Performs internal optimizations for oneapi::mkl::sparse::gemv by analyzing -the matrix structure. - -.. rubric:: Description and Assumptions - -The oneapi::mkl::sparse::optimize_gemv routine analyzes matrix structure -and performs optimizations. Optimized data is then stored in -the handle. - - -.. rubric:: Syntax - -.. code-block:: cpp - - namespace oneapi::mkl::sparse { - - sycl::event optimize_gemv (sycl::queue &queue, - oneapi::mkl::transpose transpose_val, - oneapi::mkl::sparse::matrix_handle_t handle, - const std::vector &dependencies = {}); - - } - -.. container:: section - - .. rubric:: Input Parameters - - queue - Specifies the SYCL command queue which will be used for SYCL - kernels execution. - - - transpose_val - Specifies operation ``op()`` on input matrix. The possible options - are described in :ref:`onemkl_enum_transpose` enum class. - - - handle - Handle to object containing sparse matrix and other internal - data. Created using one of ``oneapi::mkl::sparse::set_csr_data`` or - ``oneapi::mkl::sparse::set_coo_data`` routines. - - - dependencies - List of events that oneapi::mkl::sparse::optimize_gemv routine depends on. - - -.. container:: section - - .. rubric:: Output Parameters - :class: sectiontitle - - handle - Handle might be updated with some internal optimized data by this routine. - -.. container:: section - - .. rubric:: Throws - :class: sectiontitle - - This routine 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. - - | :ref:`oneapi::mkl::computation_error` - | :ref:`oneapi::mkl::device_bad_alloc` - | :ref:`oneapi::mkl::host_bad_alloc` - | :ref:`oneapi::mkl::invalid_argument` - | :ref:`oneapi::mkl::unimplemented` - | :ref:`oneapi::mkl::uninitialized` - | :ref:`oneapi::mkl::unsupported_device` - -.. container:: section - - .. rubric:: Return Values - :class: sectiontitle - - Output event that can be waited upon or added as a - dependency for the completion of optimize_gemv routine. - -.. container:: familylinks - - - .. container:: parentlink - - - **Parent topic:** :ref:`onemkl_spblas` diff --git a/source/elements/oneMKL/source/domains/spblas/matrix_view.rst b/source/elements/oneMKL/source/domains/spblas/matrix_view.rst new file mode 100644 index 000000000..81187093a --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/matrix_view.rst @@ -0,0 +1,134 @@ +.. SPDX-FileCopyrightText: 2024 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_sparse_matrix_view_and_descr: + +Matrix view +=========== + +.. _onemkl_sparse_matrix_descriptor: + +matrix_descr +------------ + +.. rubric:: Definition + +.. code:: cpp + + namespace oneapi::mkl::sparse { + + enum class matrix_descr { + general, + symmetric, + hermitian, + triangular, + diagonal, + }; + + } + +.. container:: section + + .. rubric:: Description + + The matrix descriptor is an optional property that can optimize some + operations. + + TODO: Clarify are triangular operations going to require a triangular + matrix_descr or should it be ignored? + + .. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - Value + - Description + * - ``general`` + - General case, use complete data. + * - ``symmetric`` + - View as symmetric, use given triangular part. + * - ``hermitian`` + - View as hermitian, use given triangular part. + * - ``triangular`` + - View as triangular, use given triangular part. + * - ``diagonal`` + - View as diagonal, use only main diagonal values. + +.. _onemkl_sparse_matrix_view: + +matrix_view +----------- + +.. rubric:: Definition + +.. code:: cpp + + namespace oneapi::mkl::sparse { + + struct matrix_view { + matrix_descr type_view = matrix_descr::general; + uplo uplo_view = uplo::lower; + diag diag_view = diag::nonunit; + + matrix_view() = default; + + matrix_view(matrix_descr type_view); + }; + + } + +.. container:: section + + .. rubric:: Description + + The matrix view holds information to specify which part of the matrix should + be read without changing the matrix's data. + + See :ref:`onemkl_sparse_matrix_descriptor`, :ref:`onemkl_enum_uplo` and + :ref:`onemkl_enum_diag` fot a description of the members. + + The ``uplo_view`` member is only used if ``type_view`` is ``symmetric``, + ``hermitian`` or ``triangular``. + + The ``diag_view`` member is only used if ``type_view`` is ``diagonal``. + + .. rubric:: Syntax + + .. code-block:: cpp + + namespace oneapi::mkl::sparse { + + matrix_view::matrix_view () = default; + + } + + .. container:: section + + .. rubric:: Default Constructor + + Initializes the ``matrix_view`` with the default values as shown in the class + definition. + + .. rubric:: Syntax + + .. code-block:: cpp + + namespace oneapi::mkl::sparse { + + matrix_view::matrix_view(matrix_descr type_view); + + } + + .. container:: section + + .. rubric:: Constructor from a matrix_descr + + Initializes the ``matrix_view`` with the provided ``matrix_descr``. By default + the other members are initialized to the same value as the default + constructor. + + If the ``matrix_desc`` is ``diagonal``, ``diag_view`` is initialized to + ``diag::unit``. + +**Parent topic:** :ref:`onemkl_spblas` diff --git a/source/elements/oneMKL/source/domains/spblas/matrixinit.rst b/source/elements/oneMKL/source/domains/spblas/matrixinit.rst deleted file mode 100644 index 66db35082..000000000 --- a/source/elements/oneMKL/source/domains/spblas/matrixinit.rst +++ /dev/null @@ -1,75 +0,0 @@ -.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation -.. -.. SPDX-License-Identifier: CC-BY-4.0 - -.. _onemkl_sparse_init_matrix_handle: - -init_matrix_handle -================== - - -Initializes a matrix_handle_t object to default values. - - -.. rubric:: Description and Assumptions - -The oneapi::mkl::sparse::init_matrix_handle function initializes the -``matrix_handle_t`` object with default values. - - -.. rubric:: Syntax - - -.. code-block:: cpp - - namespace oneapi::mkl::sparse { - - void init_matrix_handle (sycl::queue &queue, - oneapi::mkl::sparse::matrix_handle_t *p_handle); - - } - -.. container:: section - - - .. rubric:: Input parameters - - queue - The SYCL command queue which will be used for SYCL kernels execution. - - p_handle - The address of the sparse::matrix_handle_t ``p_handle`` object to be initialized. - This initialization routine must only be called on an uninitialized matrix_handle_t object. - -.. container:: section - - .. rubric:: Output parameters - - p_handle - On return, the address is updated to point to a newly allocated and initialized matrix_handle_t object - that can be filled and used to perform sparse BLAS operations. - - -.. container:: section - - .. rubric:: Throws - :class: sectiontitle - - This routine 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. - - | :ref:`oneapi::mkl::device_bad_alloc` - | :ref:`oneapi::mkl::host_bad_alloc` - | :ref:`oneapi::mkl::invalid_argument` - | :ref:`oneapi::mkl::unimplemented` - | :ref:`oneapi::mkl::uninitialized` - | :ref:`oneapi::mkl::unsupported_device` - -.. container:: familylinks - - - .. container:: parentlink - - - **Parent topic:** :ref:`onemkl_spblas` diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst new file mode 100644 index 000000000..3f60a203f --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst @@ -0,0 +1,393 @@ +.. SPDX-FileCopyrightText: 2024 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_sparse_spmm_header: + +spmm +==== + +Computes a sparse matrix-dense matrix product. + +.. rubric:: Description and Assumptions + +The ``oneapi::mkl::sparse::spmm`` routine computes a sparse matrix-dense matrix +product defined as: + +.. math:: + + C \leftarrow \alpha \cdot \text{op}(A) \cdot \text{op}(B) + \beta \cdot C + +where :math:`\alpha` and :math:`\beta` are scalars, :math:`A` is a sparse +matrix, :math:`B` and :math:`C` are dense matrices, :math:`\text{op}()` is a +matrix modifier for :math:`A` and :math:`B` using the following description: + +.. math:: + + \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} + +and :math:`\text{op}(A)` is an ``m``-by-``k`` matrix , :math:`\text{op}(B)` is +an ``k``-by-``n`` matrix, and :math:`C` is an ``m``-by-``n`` matrix. + +.. _onemkl_sparse_spmm_descr: + +spmm_descr +---------- + +.. rubric:: Definition + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + struct spmm_descr; + using spmm_descr_t = spmm_descr*; + } + +.. container:: section + + .. rubric:: Description + + Defines ``spmm_descr_t`` as an opaque pointer to the incomplete type + ``spmm_descr``. Each backend may provide a different implementation of the + type ``spmm_descr``. + +.. _onemkl_sparse_init_spmm_descr: + +init_spmm_descr +--------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + void init_spmm_descr (sycl::queue &queue, + oneapi::mkl::sparse::spmm_descr_t *p_spmm_descr); + + } + +.. container:: section + + .. rubric:: Input parameters + + queue + The SYCL command queue which will be used for SYCL kernels execution. + + p_spmm_descr + The address of the ``p_spmm_descr`` object to be initialized. Must only be + called on an uninitialized ``spmm_descr_t`` object. + +.. container:: section + + .. rubric:: Output parameters + + p_spmm_descr + On return, the address is updated to point to a newly allocated and + initialized ``spmm_descr_t`` object that can be used to perform spmm. + +.. container:: section + + .. rubric:: 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. + + | :ref:`oneapi::mkl::host_bad_alloc` + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::unsupported_device` + +.. _onemkl_sparse_release_spmm_descr: + +release_spmm_descr +------------------ + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + void release_spmm_descr (sycl::queue &queue, + oneapi::mkl::sparse::spmm_descr_t spmm_descr); + + } + +.. container:: section + + .. rubric:: Input parameters + + queue + The SYCL command queue which will be used for SYCL kernels execution. + + spmm_descr + Descriptor initialized with ``init_spmm_descr``. + +.. container:: section + + .. rubric:: 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. + + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::unsupported_device` + +.. _onemkl_sparse_spmm_alg: + +spmm_alg +-------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + enum class spmm_alg { + default_alg, + coo_alg1, + coo_alg2, + coo_alg3, + coo_alg4, + csr_alg1, + csr_alg2, + csr_alg3, + }; + + } + +.. list-table:: + :header-rows: 1 + :widths: 10 30 45 + + * - Value + - Description + - Backend equivalent + * - ``default_alg`` + - Default algorithm. + - | MKL: N/A + | cuSPARSE: ``CUSPARSE_SPMM_ALG_DEFAULT`` + | rocSPARSE: ``rocsparse_spmm_alg_default`` + * - ``coo_alg1`` + - Should provide best performance for COO format, small ``nnz`` and + column-major layout. + - | MKL: N/A + | cuSPARSE: ``CUSPARSE_SPMM_COO_ALG1`` + | rocSPARSE: ``rocsparse_spmm_alg_coo_segmented`` + * - ``coo_alg2`` + - Should provide best performance for COO format and column-major layout. + Produces deterministic results. + - | MKL: N/A + | cuSPARSE: ``CUSPARSE_SPMM_COO_ALG2`` + | rocSPARSE: ``rocsparse_spmm_alg_coo_atomic`` + * - ``coo_alg3`` + - Should provide best performance for COO format and large ``nnz``. + - | MKL: N/A + | cuSPARSE: ``CUSPARSE_SPMM_COO_ALG3`` + | rocSPARSE: ``rocsparse_spmm_alg_coo_segmented_atomic`` + * - ``coo_alg4`` + - Should provide best performance for COO format and row-major layout. + - | MKL: N/A + | cuSPARSE: ``CUSPARSE_SPMM_COO_ALG4`` + | rocSPARSE: N/A + * - ``csr_alg1`` + - Should provide best performance for CSR format and column-major layout. + - | MKL: N/A + | cuSPARSE: ``CUSPARSE_SPMM_CSR_ALG1`` + | rocSPARSE: ``rocsparse_spmm_alg_csr`` + * - ``csr_alg2`` + - Should provide best performance for CSR format and row-major layout. + - | MKL: N/A + | cuSPARSE: ``CUSPARSE_SPMM_CSR_ALG2`` + | rocSPARSE: ``rocsparse_spmm_alg_csr_row_split`` + * - ``csr_alg3`` + - Deterministic algorithm for CSR format. + - | MKL: N/A + | cuSPARSE: ``CUSPARSE_SPMM_CSR_ALG3`` + | rocSPARSE: ``rocsparse_spmm_alg_csr_merge`` + +.. _onemkl_sparse_spmm: + +spmm +---- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + void spmm_buffer_size( + sycl::queue &queue, + oneapi::mkl::transpose opA, + oneapi::mkl::transpose opB, + void* alpha, + oneapi::mkl::sparse::matrix_view A_view, + oneapi::mkl::sparse::matrix_handle_t A_handle, + oneapi::mkl::sparse::dense_matrix_handle_t B_handle, + void* beta, + oneapi::mkl::sparse::dense_matrix_handle_t C_handle, + oneapi::mkl::sparse::spmm_alg alg, + oneapi::mkl::sparse::spmm_descr_t spmm_descr, + std::size_t &temp_buffer_size, + ); + + void spmm_optimize( + sycl::queue &queue, + oneapi::mkl::transpose opA, + oneapi::mkl::transpose opB, + void* alpha, + oneapi::mkl::sparse::matrix_view A_view, + oneapi::mkl::sparse::matrix_handle_t A_handle, + oneapi::mkl::sparse::dense_matrix_handle_t B_handle, + void* beta, + oneapi::mkl::sparse::dense_matrix_handle_t C_handle, + oneapi::mkl::sparse::spmm_alg alg, + oneapi::mkl::sparse::spmm_descr_t spmm_descr, + sycl::buffer workspace, + ); + + sycl::event spmm_optimize( + sycl::queue &queue, + oneapi::mkl::transpose opA, + oneapi::mkl::transpose opB, + void* alpha, + oneapi::mkl::sparse::matrix_view A_view, + oneapi::mkl::sparse::matrix_handle_t A_handle, + oneapi::mkl::sparse::dense_matrix_handle_t B_handle, + void* beta, + oneapi::mkl::sparse::dense_matrix_handle_t C_handle, + oneapi::mkl::sparse::spmm_alg alg, + oneapi::mkl::sparse::spmm_descr_t spmm_descr, + void* workspace, + const std::vector &dependencies = {}, + ); + + sycl::event spmm( + sycl::queue &queue, + oneapi::mkl::transpose opA, + oneapi::mkl::transpose opB, + void* alpha, + oneapi::mkl::sparse::matrix_view A_view, + oneapi::mkl::sparse::matrix_handle_t A_handle, + oneapi::mkl::sparse::dense_matrix_handle_t B_handle, + void* beta, + oneapi::mkl::sparse::dense_matrix_handle_t C_handle, + oneapi::mkl::sparse::spmm_alg alg, + oneapi::mkl::sparse::spmm_descr_t spmm_descr, + const std::vector &dependencies = {}, + ); + + } + +.. container:: section + + .. rubric:: Notes + + - ``spmm_buffer_size`` and ``spmm_optimize`` must be called at least once before ``spmm`` + with the same arguments. ``spmm`` can then be called multiple times. + - The data of the handles can be reset-ed before each call to ``spmm``. + - ``spmm_optimize`` and ``spmm`` are asynchronous. + - The algorithm defaults to ``spmm_alg::default_alg`` if a backend does not + support the provided algorithm. + + .. rubric:: Input Parameters + + queue + The SYCL command queue which will be used for SYCL kernels execution. + + opA + Specifies operation ``op()`` on the input matrix A. The possible options + are described in :ref:`onemkl_enum_transpose` enum class. + + opB + Specifies operation ``op()`` on the input matrix B. The possible options + are described in :ref:`onemkl_enum_transpose` enum class. + + alpha + Host or USM pointer representing :math:`\alpha`. The USM allocation can be + on the host or device. + + A_view + Specifies which part of the handle should be read as described by + :ref:`onemkl_sparse_matrix_view`. + + A_handle + Sparse matrix handle object representing :math:`A`. + + B_handle + Dense matrix handle object representing :math:`B`. + + beta + Host or USM pointer representing :math:`\beta`. The USM allocation can be + on the host or device. + + C_handle + Dense matrix handle object representing :math:`C`. + + alg + Specifies the :ref:`spmm algorithm` to use. + + spmm_descr + Initialized :ref:`spmm 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. If it is a buffer, its lifetime is extended + until the :ref:`spmm descriptor` is released. If + it is a USM pointer, it must not be free'd until ``spmm`` 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. Defaults to no dependencies. + +.. container:: section + + .. rubric:: Output Parameters + + temp_buffer_size + Output buffer size in bytes. A temporary workspace of this size must be + allocated to perform the specified spmm. + + C_handle + Dense matrix handle object representing :math:`C`, result of the ``spmm`` + operation. + +.. container:: section + + .. rubric:: Return Values + + Output event that can be waited upon or added as a dependency for the + completion of the function. + +.. container:: section + + .. rubric:: 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. + + | :ref:`oneapi::mkl::computation_error` + | :ref:`oneapi::mkl::device_bad_alloc` + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::uninitialized` + | :ref:`oneapi::mkl::unsupported_device` + +**Parent topic:** :ref:`onemkl_spblas` diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst new file mode 100644 index 000000000..20495be5f --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst @@ -0,0 +1,371 @@ +.. SPDX-FileCopyrightText: 2024 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_sparse_spmv_header: + +spmv +==== + +Computes a sparse matrix-dense vector product. + +.. rubric:: Description and Assumptions + +The ``oneapi::mkl::sparse::spmv`` routine computes a sparse matrix-dense vector +product defined as: + +.. math:: + + y \leftarrow \alpha \cdot \text{op}(A) \cdot x + \beta \cdot y + +where :math:`\alpha` and :math:`\beta` are scalars, :math:`A` is a sparse +matrix, :math:`x` and :math:`y` are dense vectors, :math:`\text{op}()` is a +matrix modifier for :math:`A` using the following description: + +.. math:: + + \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} + +and :math:`\text{op}(A)` is an ``m``-by-``n`` matrix , :math:`x` is a vector of +size ``n`` and :math:`y` is a vector of size ``m``. + +.. _onemkl_sparse_spmv_descr: + +spmv_descr +---------- + +.. rubric:: Definition + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + struct spmv_descr; + using spmv_descr_t = spmv_descr*; + } + +.. container:: section + + .. rubric:: Description + + Defines ``spmv_descr_t`` as an opaque pointer to the incomplete type + ``spmv_descr``. Each backend may provide a different implementation of the + type ``spmv_descr``. + +.. _onemkl_sparse_init_spmv_descr: + +init_spmv_descr +--------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + void init_spmv_descr (sycl::queue &queue, + oneapi::mkl::sparse::spmv_descr_t *p_spmv_descr); + + } + +.. container:: section + + .. rubric:: Input parameters + + queue + The SYCL command queue which will be used for SYCL kernels execution. + + p_spmv_descr + The address of the ``p_spmv_descr`` object to be initialized. Must only be + called on an uninitialized ``spmv_descr_t`` object. + +.. container:: section + + .. rubric:: Output parameters + + p_spmv_descr + On return, the address is updated to point to a newly allocated and + initialized ``spmv_descr_t`` object that can be used to perform spmv. + +.. container:: section + + .. rubric:: 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. + + | :ref:`oneapi::mkl::host_bad_alloc` + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::unsupported_device` + +.. _onemkl_sparse_release_spmv_descr: + +release_spmv_descr +------------------ + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + void release_spmv_descr (sycl::queue &queue, + oneapi::mkl::sparse::spmv_descr_t spmv_descr); + + } + +.. container:: section + + .. rubric:: Input parameters + + queue + The SYCL command queue which will be used for SYCL kernels execution. + + spmv_descr + Descriptor initialized with ``init_spmv_descr``. + +.. container:: section + + .. rubric:: 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. + + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::unsupported_device` + +.. _onemkl_sparse_spmv_alg: + +spmv_alg +-------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + enum class spmv_alg { + default_alg, + coo_alg1, + coo_alg2, + csr_alg1, + csr_alg2, + csr_alg3, + }; + + } + +.. list-table:: + :header-rows: 1 + :widths: 10 30 45 + + * - Value + - Description + - Backend equivalent + * - ``default_alg`` + - Default algorithm. + - | MKL: N/A + | cuSPARSE: ``CUSPARSE_SPMV_ALG_DEFAULT`` + | rocSPARSE: ``rocsparse_spmv_alg_default`` + * - ``coo_alg1`` + - Default algorithm for COO format. + - | MKL: N/A + | cuSPARSE: ``CUSPARSE_SPMV_COO_ALG1`` + | rocSPARSE: ``rocsparse_spmv_alg_coo`` + * - ``coo_alg2`` + - Deterministic algorithm for COO format. + - | MKL: N/A + | cuSPARSE: ``CUSPARSE_SPMV_COO_ALG2`` + | rocSPARSE: ``rocsparse_spmv_alg_coo_atomic`` + * - ``csr_alg1`` + - Default algorithm for CSR format. + - | MKL: N/A + | cuSPARSE: ``CUSPARSE_SPMV_CSR_ALG1`` + | rocSPARSE: ``rocsparse_spmv_alg_csr_adaptive`` + * - ``csr_alg2`` + - Deterministic algorithm for CSR format. + - | MKL: N/A + | cuSPARSE: ``CUSPARSE_SPMV_CSR_ALG2`` + | rocSPARSE: ``rocsparse_spmv_alg_csr_stream`` + * - ``csr_alg3`` + - LRB variant of the algorithm for CSR format. + - | MKL: N/A + | cuSPARSE: N/A + | rocSPARSE: ``rocsparse_spmv_alg_csr_lrb`` + +.. _onemkl_sparse_spmv: + +spmv +---- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + void spmv_buffer_size( + sycl::queue &queue, + oneapi::mkl::transpose opA, + void* alpha, + oneapi::mkl::sparse::matrix_view A_view, + oneapi::mkl::sparse::matrix_handle_t A_handle, + oneapi::mkl::sparse::dense_vector_handle_t x_handle, + void* beta, + oneapi::mkl::sparse::dense_vector_handle_t y_handle, + oneapi::mkl::sparse::spmv_alg alg, + oneapi::mkl::sparse::spmv_descr_t spmv_descr, + std::size_t &temp_buffer_size, + ); + + void spmv_optimize( + sycl::queue &queue, + oneapi::mkl::transpose opA, + void* alpha, + oneapi::mkl::sparse::matrix_view A_view, + oneapi::mkl::sparse::matrix_handle_t A_handle, + oneapi::mkl::sparse::dense_vector_handle_t x_handle, + void* beta, + oneapi::mkl::sparse::dense_vector_handle_t y_handle, + oneapi::mkl::sparse::spmv_alg alg, + oneapi::mkl::sparse::spmv_descr_t spmv_descr, + sycl::buffer workspace, + ); + + sycl::event spmv_optimize( + sycl::queue &queue, + oneapi::mkl::transpose opA, + void* alpha, + oneapi::mkl::sparse::matrix_view A_view, + oneapi::mkl::sparse::matrix_handle_t A_handle, + oneapi::mkl::sparse::dense_vector_handle_t x_handle, + void* beta, + oneapi::mkl::sparse::dense_vector_handle_t y_handle, + oneapi::mkl::sparse::spmv_alg alg, + oneapi::mkl::sparse::spmv_descr_t spmv_descr, + void* workspace, + const std::vector &dependencies = {}, + ); + + sycl::event spmv( + sycl::queue &queue, + oneapi::mkl::transpose opA, + void* alpha, + oneapi::mkl::sparse::matrix_view A_view, + oneapi::mkl::sparse::matrix_handle_t A_handle, + oneapi::mkl::sparse::dense_vector_handle_t x_handle, + void* beta, + oneapi::mkl::sparse::dense_vector_handle_t y_handle, + oneapi::mkl::sparse::spmv_alg alg, + oneapi::mkl::sparse::spmv_descr_t spmv_descr, + const std::vector &dependencies = {}, + ); + + } + +.. container:: section + + .. rubric:: Notes + + - ``spmv_buffer_size`` and ``spmv_optimize`` must be called at least once before ``spmv`` + with the same arguments. ``spmv`` can then be called multiple times. + - The data of the handles can be reset-ed before each call to ``spmv``. + - ``spmv_optimize`` and ``spmv`` are asynchronous. + - The algorithm defaults to ``spmv_alg::default_alg`` if a backend does not + support the provided algorithm. + + .. rubric:: 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 :ref:`onemkl_enum_transpose` enum class. + + alpha + Host or USM pointer representing :math:`\alpha`. The USM allocation can be + on the host or device. + + A_view + Specifies which part of the handle should be read as described by + :ref:`onemkl_sparse_matrix_view`. + + A_handle + Sparse matrix handle object representing :math:`A`. + + x_handle + Dense vector handle object representing :math:`x`. + + beta + Host or USM pointer representing :math:`\beta`. The USM allocation can be + on the host or device. + + y_handle + Dense vector handle object representing :math:`y`. + + alg + Specifies the :ref:`spmv algorithm` to use. + + spmv_descr + Initialized :ref:`spmv 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. If it is a buffer, its lifetime is extended + until the :ref:`spmv descriptor` is released. If + it is a USM pointer, it must not be free'd until ``spmv`` 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. Defaults to no dependencies. + +.. container:: section + + .. rubric:: Output Parameters + + temp_buffer_size + Output buffer size in bytes. A temporary workspace of this size must be + allocated to perform the specified spmv. + + y_handle + Dense vector handle object representing :math:`y`, result of the ``spmv`` + operation. + +.. container:: section + + .. rubric:: Return Values + + Output event that can be waited upon or added as a dependency for the + completion of the function. + +.. container:: section + + .. rubric:: 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. + + | :ref:`oneapi::mkl::computation_error` + | :ref:`oneapi::mkl::device_bad_alloc` + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::uninitialized` + | :ref:`oneapi::mkl::unsupported_device` + +**Parent topic:** :ref:`onemkl_spblas` diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst new file mode 100644 index 000000000..2e1553e13 --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst @@ -0,0 +1,333 @@ +.. SPDX-FileCopyrightText: 2024 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_sparse_spsv_header: + +spsv +==== + +Solves a system of linear equations for a triangular sparse matrix. + +.. rubric:: Description and Assumptions + +The ``oneapi::mkl::sparse::spsv`` routine solves a system of linear equations +for a square matrix: + +.. math:: + + \text{op}(A) \cdot y \leftarrow \alpha \cdot x + +where :math:`\alpha` is a scalar, :math:`A` is a triangular sparse matrix, :math:`x` and :math:`y` are +dense vectors, :math:`\text{op}()` is a matrix modifier for :math:`A` using the +following description: + +.. math:: + + \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} + +and :math:`\text{op}(A)` is an ``m``-by-``m`` matrix , :math:`x` and :math:`y` +are vectors of size ``m``. + +.. _onemkl_sparse_spsv_descr: + +spsv_descr +---------- + +.. rubric:: Definition + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + struct spsv_descr; + using spsv_descr_t = spsv_descr*; + } + +.. container:: section + + .. rubric:: 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``. + +.. _onemkl_sparse_init_spsv_descr: + +init_spsv_descr +--------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + void init_spsv_descr (sycl::queue &queue, + oneapi::mkl::sparse::spsv_descr_t *p_spsv_descr); + + } + +.. container:: section + + .. rubric:: 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. + +.. container:: section + + .. rubric:: 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. + +.. container:: section + + .. rubric:: 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. + + | :ref:`oneapi::mkl::host_bad_alloc` + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::unsupported_device` + +.. _onemkl_sparse_release_spsv_descr: + +release_spsv_descr +------------------ + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + void release_spsv_descr (sycl::queue &queue, + oneapi::mkl::sparse::spsv_descr_t spsv_descr); + + } + +.. container:: section + + .. rubric:: Input parameters + + queue + The SYCL command queue which will be used for SYCL kernels execution. + + spsv_descr + Descriptor initialized with ``init_spsv_descr``. + +.. container:: section + + .. rubric:: 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. + + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::unsupported_device` + +.. _onemkl_sparse_spsv_alg: + +spsv_alg +-------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + enum class spsv_alg { + default_alg, + }; + + } + +.. list-table:: + :header-rows: 1 + :widths: 10 30 45 + + * - Value + - Description + - Backend equivalent + * - ``default_alg`` + - Default algorithm. + - | MKL: N/A + | cuSPARSE: ``CUSPARSE_SPSV_ALG_DEFAULT`` + | rocSPARSE: ``rocsparse_spsv_alg_default`` + +.. _onemkl_sparse_spsv: + +spsv +---- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + void spsv_buffer_size( + sycl::queue &queue, + oneapi::mkl::transpose opA, + void* alpha, + oneapi::mkl::sparse::matrix_view A_view, + oneapi::mkl::sparse::matrix_handle_t A_handle, + oneapi::mkl::sparse::dense_vector_handle_t x_handle, + oneapi::mkl::sparse::dense_vector_handle_t y_handle, + oneapi::mkl::sparse::spsv_alg alg, + oneapi::mkl::sparse::spsv_descr_t spsv_descr, + std::size_t &temp_buffer_size, + ); + + void spsv_optimize( + sycl::queue &queue, + oneapi::mkl::transpose opA, + void* alpha, + oneapi::mkl::sparse::matrix_view A_view, + oneapi::mkl::sparse::matrix_handle_t A_handle, + oneapi::mkl::sparse::dense_vector_handle_t x_handle, + oneapi::mkl::sparse::dense_vector_handle_t y_handle, + oneapi::mkl::sparse::spsv_alg alg, + oneapi::mkl::sparse::spsv_descr_t spsv_descr, + sycl::buffer workspace, + ); + + sycl::event spsv_optimize( + sycl::queue &queue, + oneapi::mkl::transpose opA, + void* alpha, + oneapi::mkl::sparse::matrix_view A_view, + oneapi::mkl::sparse::matrix_handle_t A_handle, + oneapi::mkl::sparse::dense_vector_handle_t x_handle, + oneapi::mkl::sparse::dense_vector_handle_t y_handle, + oneapi::mkl::sparse::spsv_alg alg, + oneapi::mkl::sparse::spsv_descr_t spsv_descr, + void* workspace, + const std::vector &dependencies = {}, + ); + + sycl::event spsv( + sycl::queue &queue, + oneapi::mkl::transpose opA, + void* alpha, + oneapi::mkl::sparse::matrix_view A_view, + oneapi::mkl::sparse::matrix_handle_t A_handle, + oneapi::mkl::sparse::dense_vector_handle_t x_handle, + oneapi::mkl::sparse::dense_vector_handle_t y_handle, + oneapi::mkl::sparse::spsv_alg alg, + oneapi::mkl::sparse::spsv_descr_t spsv_descr, + const std::vector &dependencies = {}, + ); + + } + +.. container:: section + + .. rubric:: 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. + - The data of the handles can be reset-ed before each call to ``spsv``. + - ``spsv_optimize`` and ``spsv`` are asynchronous. + - The algorithm defaults to ``spsv_alg::default_alg`` if a backend does not + support the provided algorithm. + + .. rubric:: 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 :ref:`onemkl_enum_transpose` enum class. + + alpha + Host or USM pointer representing :math:`\alpha`. The USM allocation can be + on the host or device. + + A_view + Specifies which part of the handle should be read as described by + :ref:`onemkl_sparse_matrix_view`. + + A_handle + Sparse matrix handle object representing :math:`A`. + + x_handle + Dense vector handle object representing :math:`x`. + + y_handle + Dense vector handle object representing :math:`y`. + + alg + Specifies the :ref:`spsv algorithm` to use. + + spsv_descr + Initialized :ref:`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. If it is a buffer, its lifetime is extended + until the :ref:`spsv descriptor` is released. If + it is a USM pointer, it must not be free'd until ``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. Defaults to no dependencies. + +.. container:: section + + .. rubric:: Output Parameters + + temp_buffer_size + Output buffer size in bytes. A temporary workspace of this size must be + allocated to perform the specified spsv. + + y_handle + Dense vector handle object representing :math:`y`, result of the ``spsv`` + operation. + +.. container:: section + + .. rubric:: Return Values + + Output event that can be waited upon or added as a dependency for the + completion of the function. + +.. container:: section + + .. rubric:: 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. + + | :ref:`oneapi::mkl::computation_error` + | :ref:`oneapi::mkl::device_bad_alloc` + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::uninitialized` + | :ref:`oneapi::mkl::unsupported_device` + +**Parent topic:** :ref:`onemkl_spblas` diff --git a/source/elements/oneMKL/source/domains/spblas/releasematrixhandle.rst b/source/elements/oneMKL/source/domains/spblas/releasematrixhandle.rst deleted file mode 100644 index 0cfd90e77..000000000 --- a/source/elements/oneMKL/source/domains/spblas/releasematrixhandle.rst +++ /dev/null @@ -1,89 +0,0 @@ -.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation -.. -.. SPDX-License-Identifier: CC-BY-4.0 - -.. _onemkl_sparse_release_matrix_handle: - -release_matrix_handle -===================== - - -Releases internal data and sets matrix_handle_t object to NULL. - - -.. rubric:: Description and Assumptions - -The oneapi::mkl::sparse::release_matrix_handle releases any internal data that the -``matrix_handle_t`` object holds and sets it with defaults values, otherwise it -throws an exception. The routine also waits for the dependencies to be finished -before releasing any data in case of USM. - - -.. rubric:: Syntax - - -.. code-block:: cpp - - namespace oneapi::mkl::sparse { - - sycl::event release_matrix_handle (sycl::queue &queue, - oneapi::mkl::sparse::matrix_handle_t *p_handle, - const std::vector &dependencies = {}); - - } - -.. container:: section - - - .. rubric:: Input parameters - - queue - The SYCL command queue which will be used for SYCL kernels execution. - - p_handle - The address of the sparse::matrix_handle_t ``p_handle`` object to be released, containing sparse matrix and other internal - data. Initialized with oneapi::mkl::sparse::init_matrix_handle routine, and filled with user data using one of the - oneapi::mkl::sparse::set__structure routines. - - dependencies - List of events that ``p_handle`` depends on. - The call waits on the events (if any) before resetting the ``p_handle`` to default values. - -.. container:: section - - .. rubric:: Output parameters - - p_handle - The address of the sparse::matrix_handle_t ``p_handle`` that will be scheduled to be updated to point to a null object - and the passed in handle will be scheduled for deallocation and cleanup. - -.. container:: section - - .. rubric:: Return Values - - sycl::event - SYCL event which can be waited upon or added as a dependency for the completion of the deallocation and cleanup routines. - -.. container:: section - - .. rubric:: Throws - :class: sectiontitle - - This routine 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. - - | :ref:`oneapi::mkl::device_bad_alloc` - | :ref:`oneapi::mkl::host_bad_alloc` - | :ref:`oneapi::mkl::invalid_argument` - | :ref:`oneapi::mkl::unimplemented` - | :ref:`oneapi::mkl::uninitialized` - | :ref:`oneapi::mkl::unsupported_device` - -.. container:: familylinks - - - .. container:: parentlink - - - **Parent topic:** :ref:`onemkl_spblas` diff --git a/source/elements/oneMKL/source/domains/spblas/setcoostructure.rst b/source/elements/oneMKL/source/domains/spblas/setcoostructure.rst deleted file mode 100644 index 23b4b31a3..000000000 --- a/source/elements/oneMKL/source/domains/spblas/setcoostructure.rst +++ /dev/null @@ -1,263 +0,0 @@ -.. SPDX-FileCopyrightText: 2024 Intel Corporation -.. -.. SPDX-License-Identifier: CC-BY-4.0 - -.. _onemkl_sparse_set_coo_data: - -set_coo_data -============ - -Takes a matrix handle and the input COO matrix arrays and fills the internal COO data structure. - -.. rubric:: Description and Assumptions - - -Refer to :ref:`onemkl_sparse_supported_types` for a -list of supported ```` and ````. -The mkl::sparse::set_coo_data routine takes a matrix handle -for a sparse matrix of dimensions *nrows* -by- *ncols* -represented in the COO format, and fills the internal -COO data structure. - -The mkl::sparse::set_coo_data routine defined below takes in the -number of non-zero elements in the sparse matrix as an argument. -However, in certain math operations where the output is a sparse matrix, -e.g., sparse matrix addition (sparse matrix + sparse matrix = sparse matrix), -and multiplication of two sparse matrices, the number of non-zero -elements in the output sparse matrix is not known in advance and -must be calculated as part of the operation/API. Such APIs are currently -not a part of the current oneMKL Specification, but will be added in the -future. Therefore, it is important for the set_coo_data API to be able -to handle mutliple calls to build the sparse matrix as function arguments -become known and arrays are allocated with the correct sizes. In particular, -the set_coo_data API must handle the case where the number of non-zero -elements in the matrix are unknown and the matrix arrays are ``nullptr`` -or zero-sized ``sycl::buffer`` objects as applicable. This behavior is -currently left to be implementation-defined, but may be clarified in the -oneMKL Specification in the future. - -.. _onemkl_sparse_set_coo_data_buffer: - -set_coo_data (Buffer version) ------------------------------ - -.. rubric:: Syntax - -.. code-block:: cpp - - namespace oneapi::mkl::sparse { - - void set_coo_data (sycl::queue &queue, - oneapi::mkl::sparse::matrix_handle_t handle, - const intType nrows, - const intType ncols, - const intType nnz, - oneapi::mkl::index_base index, - sycl::buffer &row_ind, - sycl::buffer &col_ind, - sycl::buffer &val); - - } - -.. container:: section - - .. rubric:: Input Parameters - - queue - The SYCL command queue which will be used for SYCL kernel execution. - - handle - Handle to object containing sparse matrix and other internal - data for subsequent DPC++ Sparse BLAS operations. - - - nrows - Number of rows of the input matrix. - - - ncols - Number of columns of the input matrix. - - - nnz - Number of non-zero entries in the matrix (which may include explicit - zeros). - - - index - Indicates how input arrays are indexed. - The possible options are - described in :ref:`onemkl_enum_index_base` enum class. - - - row_ind - SYCL memory object which stores an array of length ``nnz`` - containing row indices in ``index``-based numbering. - Refer to :ref:`onemkl_sparse_coo` format for detailed - description of ``row_ind``. - - - col_ind - SYCL memory object which stores an array of length ``nnz`` - containing column indices in ``index``-based numbering. - Refer to :ref:`onemkl_sparse_coo` format for detailed - description of ``col_ind``. - - - val - SYCL memory object which stores an array of length ``nnz`` - containing non-zero elements (and possibly explicit zeros) of the - input matrix. Refer to :ref:`onemkl_sparse_coo` format for detailed - description of ``val``. - - -.. container:: section - - - .. rubric:: Output Parameters - :class: sectiontitle - - - handle - Handle to object containing sparse matrix and other internal - data for subsequent SYCL Sparse BLAS operations. - -.. container:: section - - .. rubric:: Throws - :class: sectiontitle - - This routine 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. - - | :ref:`oneapi::mkl::computation_error` - | :ref:`oneapi::mkl::device_bad_alloc` - | :ref:`oneapi::mkl::host_bad_alloc` - | :ref:`oneapi::mkl::invalid_argument` - | :ref:`oneapi::mkl::unimplemented` - | :ref:`oneapi::mkl::uninitialized` - | :ref:`oneapi::mkl::unsupported_device` - -.. _onemkl_sparse_set_coo_data_usm: - -set_coo_data (USM version) --------------------------- - -.. rubric:: Syntax - -.. code-block:: cpp - - namespace oneapi::mkl::sparse { - - sycl::event set_coo_data (sycl::queue &queue, - oneapi::mkl::sparse::matrix_handle_t handle, - const intType nrows, - const intType ncols, - const intType nnz, - oneapi::mkl::index_base index, - intType *row_ind, - intType *col_ind, - fp *val, - const std::vector &dependencies = {}); - - } - -.. container:: section - - .. rubric:: Input Parameters - - queue - The SYCL command queue which will be used for SYCL kernel execution. - - handle - Handle to object containing sparse matrix and other internal - data for subsequent DPC++ Sparse BLAS operations. - - - nrows - Number of rows of the input matrix. - - - ncols - Number of columns of the input matrix. - - - nnz - Number of non-zero entries in the matrix (which may include explicit - zeros). - - - index - Indicates how input arrays are indexed. - The possible options are - described in :ref:`onemkl_enum_index_base` enum class. - - - row_ind - USM object which stores an array of length ``nnz`` - containing row indices in ``index``-based numbering. - Refer to :ref:`onemkl_sparse_coo` format for detailed - description of ``row_ind`` - - - col_ind - USM object which stores an array of length ``nnz`` - containing column indices in ``index``-based numbering. - Refer to :ref:`onemkl_sparse_coo` format for detailed - description of ``col_ind`` - - - val - USM object which stores an array of length ``nnz`` - containing non-zero elements (and possibly explicit zeros) of the - input matrix. Refer to :ref:`onemkl_sparse_coo` format for - detailed description of ``val`` - - dependencies - A vector of type const std::vector & containing the list of events - that the oneapi::mkl::sparse::set_coo_data routine depends on. - -.. container:: section - - .. rubric:: Output Parameters - :class: sectiontitle - - - handle - Handle to object containing sparse matrix and other internal - data for subsequent SYCL Sparse BLAS operations. - -.. container:: section - - .. rubric:: Return Values - :class: sectiontitle - - sycl::event - A sycl::event that can be used to track the completion of asynchronous events - that were enqueued during the API call that continue the chain of events from the input dependencies. - -.. container:: section - - .. rubric:: Throws - :class: sectiontitle - - This routine 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. - - | :ref:`oneapi::mkl::computation_error` - | :ref:`oneapi::mkl::device_bad_alloc` - | :ref:`oneapi::mkl::host_bad_alloc` - | :ref:`oneapi::mkl::invalid_argument` - | :ref:`oneapi::mkl::unimplemented` - | :ref:`oneapi::mkl::uninitialized` - | :ref:`oneapi::mkl::unsupported_device` - -.. container:: familylinks - - - .. container:: parentlink - - - **Parent topic:** :ref:`onemkl_spblas` diff --git a/source/elements/oneMKL/source/domains/spblas/setcsrstructure.rst b/source/elements/oneMKL/source/domains/spblas/setcsrstructure.rst deleted file mode 100644 index 11c5e07c0..000000000 --- a/source/elements/oneMKL/source/domains/spblas/setcsrstructure.rst +++ /dev/null @@ -1,261 +0,0 @@ -.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation -.. -.. SPDX-License-Identifier: CC-BY-4.0 - -.. _onemkl_sparse_set_csr_data: - -set_csr_data -============ - -Takes a matrix handle and the input CSR matrix arrays and fills the internal CSR data structure. - -.. rubric:: Description and Assumptions - - -Refer to :ref:`onemkl_sparse_supported_types` for a -list of supported ```` and ````. -The mkl::sparse::set_csr_data routine takes a matrix handle -for a sparse matrix of dimensions *nrows* -by- *ncols* -represented in the CSR format, and fills the internal -CSR data structure. - -The mkl::sparse::set_csr_data routine defined below takes in the -number of non-zero elements in the sparse matrix as an argument. -However, in certain math operations where the output is a sparse matrix, -e.g., sparse matrix addition (sparse matrix + sparse matrix = sparse matrix), -and multiplication of two sparse matrices, the number of non-zero -elements in the output sparse matrix is not known in advance and -must be calculated as part of the operation/API. Such APIs are currently -not a part of the current oneMKL Specification, but will be added in the -future. Therefore, it is important for the set_csr_data API to be able -to handle mutliple calls to build the sparse matrix as function arguments -become known and arrays are allocated with the correct sizes. In particular, -the set_csr_data API must handle the case where the number of non-zero -elements in the matrix are unknown and the matrix arrays are ``nullptr`` -or zero-sized ``sycl::buffer`` objects as applicable. This behavior is -currently left to be implementation-defined, but may be clarified in the -oneMKL Specification in the future. - -.. _onemkl_sparse_set_csr_data_buffer: - -set_csr_data (Buffer version) ------------------------------ - -.. rubric:: Syntax - -.. code-block:: cpp - - namespace oneapi::mkl::sparse { - - void set_csr_data (sycl::queue &queue, - oneapi::mkl::sparse::matrix_handle_t handle, - const intType nrows, - const intType ncols, - const intType nnz, - oneapi::mkl::index_base index, - sycl::buffer &row_ptr, - sycl::buffer &col_ind, - sycl::buffer &val); - - } - -.. container:: section - - .. rubric:: Input Parameters - - queue - The SYCL command queue which will be used for SYCL kernel execution. - - handle - Handle to object containing sparse matrix and other internal - data for subsequent DPC++ Sparse BLAS operations. - - - nrows - Number of rows of the input matrix . - - - ncols - Number of columns of the input matrix . - - - nnz - Number of non-zero entries in the matrix (which may include explicit - zeros). - - - index - Indicates how input arrays are indexed. - The possible options are - described in :ref:`onemkl_enum_index_base` enum class. - - - row_ptr - SYCL memory object containing an array of length - ``nrows+1``. Refer to :ref:`onemkl_sparse_csr` format - for detailed description of ``row_ptr``. - - - col_ind - SYCL memory object which stores an array of length ``nnz`` - containing the column indices in ``index``-based numbering. - Refer to :ref:`onemkl_sparse_csr` format for detailed - description of ``col_ind``. - - - val - SYCL memory object which stores an array of length ``nnz`` - containing non-zero elements (and possibly explicit zeros) of the - input matrix. Refer to :ref:`onemkl_sparse_csr` format for detailed - description of ``val``. - - -.. container:: section - - - .. rubric:: Output Parameters - :class: sectiontitle - - -handle - Handle to object containing sparse matrix and other internal - data for subsequent SYCL Sparse BLAS operations. - -.. container:: section - - .. rubric:: Throws - :class: sectiontitle - - This routine 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. - - | :ref:`oneapi::mkl::computation_error` - | :ref:`oneapi::mkl::device_bad_alloc` - | :ref:`oneapi::mkl::host_bad_alloc` - | :ref:`oneapi::mkl::invalid_argument` - | :ref:`oneapi::mkl::unimplemented` - | :ref:`oneapi::mkl::uninitialized` - | :ref:`oneapi::mkl::unsupported_device` - -.. _onemkl_sparse_set_csr_data_usm: - -set_csr_data (USM version) --------------------------- - -.. rubric:: Syntax - -.. code-block:: cpp - - namespace oneapi::mkl::sparse { - - sycl::event set_csr_data (sycl::queue &queue, - oneapi::mkl::sparse::matrix_handle_t handle, - const intType nrows, - const intType ncols, - const intType nnz, - oneapi::mkl::index_base index, - intType *row_ptr, - intType *col_ind, - fp *val, - const std::vector &dependencies = {}); - - } - -.. container:: section - - .. rubric:: Input Parameters - - queue - The SYCL command queue which will be used for SYCL kernel execution. - - handle - Handle to object containing sparse matrix and other internal - data for subsequent DPC++ Sparse BLAS operations. - - - nrows - Number of rows of the input matrix. - - - ncols - Number of columns of the input matrix. - - - nnz - Number of non-zero entries in the matrix (which may include explicit - zeros). - - - index - Indicates how input arrays are indexed. - The possible options are - described in :ref:`onemkl_enum_index_base` enum class. - - - row_ptr - USM object containing an array of length - ``nrows+1``. Refer to :ref:`onemkl_sparse_csr` format for - detailed description of ``row_ptr`` - - - col_ind - USM object which stores an array of length ``nnz`` - containing the column indices in ``index``-based numbering. - Refer to :ref:`onemkl_sparse_csr` format for detailed - description of ``col_ind`` - - - val - USM object which stores an array of length ``nnz`` - containing non-zero elements (and possibly explicit zeros) of the - input matrix. Refer to :ref:`onemkl_sparse_csr` format for - detailed description of ``val`` - - dependencies - A vector of type const std::vector & containing the list of events - that the oneapi::mkl::sparse::set_csr_data routine depends on. - -.. container:: section - - .. rubric:: Output Parameters - :class: sectiontitle - - - handle - Handle to object containing sparse matrix and other internal - data for subsequent SYCL Sparse BLAS operations. - -.. container:: section - - .. rubric:: Return Values - :class: sectiontitle - - sycl::event - A sycl::event that can be used to track the completion of asynchronous events - that were enqueued during the API call that continue the chain of events from the input dependencies. - -.. container:: section - - .. rubric:: Throws - :class: sectiontitle - - This routine 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. - - | :ref:`oneapi::mkl::computation_error` - | :ref:`oneapi::mkl::device_bad_alloc` - | :ref:`oneapi::mkl::host_bad_alloc` - | :ref:`oneapi::mkl::invalid_argument` - | :ref:`oneapi::mkl::unimplemented` - | :ref:`oneapi::mkl::uninitialized` - | :ref:`oneapi::mkl::unsupported_device` - -.. container:: familylinks - - - .. container:: parentlink - - - **Parent topic:** :ref:`onemkl_spblas` diff --git a/source/elements/oneMKL/source/domains/spblas/spblas.rst b/source/elements/oneMKL/source/domains/spblas/spblas.rst index 92f68a061..34fc6c6ca 100644 --- a/source/elements/oneMKL/source/domains/spblas/spblas.rst +++ b/source/elements/oneMKL/source/domains/spblas/spblas.rst @@ -1,79 +1,40 @@ -.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation +.. SPDX-FileCopyrightText: 2024 Intel Corporation .. .. SPDX-License-Identifier: CC-BY-4.0 .. _onemkl_spblas: Sparse BLAS ---------------- +=========== .. container:: - Sparse BLAS Routines provide basic operations on sparse vectors and matrices + Sparse BLAS routines provide basic operations on sparse vectors and matrices. .. container:: tablenoborder + .. list-table:: + :header-rows: 1 - .. list-table:: - :header-rows: 1 - - * - Routines - - Description - * - :ref:`onemkl_sparse_init_matrix_handle` - - Initialize the sparse matrix handle - * - :ref:`onemkl_sparse_release_matrix_handle` - - Release the sparse matrix handle - * - :ref:`onemkl_sparse_set_csr_data` - - Fills the internal CSR data structure - * - :ref:`onemkl_sparse_set_coo_data` - - Fills the internal COO data structure - * - :ref:`onemkl_sparse_optimize_gemv` - - Optimize routine for gemv - * - :ref:`onemkl_sparse_optimize_symv` - - Optimize routine for symv - * - :ref:`onemkl_sparse_optimize_trmv` - - Optimize routine for trmv - * - :ref:`onemkl_sparse_optimize_trsv` - - Optimize routine for trsv - * - :ref:`onemkl_sparse_optimize_gemm` - - Optimize routine for gemm - * - :ref:`onemkl_sparse_gemv` - - Sparse matrix-dense vector product using a general sparse matrix - * - :ref:`onemkl_sparse_gemvdot` - - Sparse matrix-dense vector product followed by dot product - * - :ref:`onemkl_sparse_symv` - - Sparse matrix-dense vector product using a symmetric sparse matrix - * - :ref:`onemkl_sparse_trmv` - - Sparse matrix-dense vector product using a triangular sparse matrix - * - :ref:`onemkl_sparse_trsv` - - Solving a linear system with a triangular sparse matrix - * - :ref:`onemkl_sparse_gemm` - - Sparse matrix-dense matrix product using a general sparse matrix - - -.. container:: - - - :ref:`onemkl_sparse_format_descriptions` + * - Routines and Objects + - Description + * - :ref:`onemkl_sparse_data_handles` + - Matrix and vector handle types + * - :ref:`onemkl_sparse_spsv_header` + - Solve a linear system with a triangular sparse matrix + * - :ref:`onemkl_sparse_spmv_header` + - Compute the product of a sparse matrix with a dense vector + * - :ref:`onemkl_sparse_spmm_header` + - Compute the product of a sparse matrix with a dense matrix .. toctree:: - :hidden: - - matrixinit - releasematrixhandle - setcsrstructure - setcoostructure - gemm - gemmoptimize - gemv - gemvdot - gemvoptimize - symv - symvoptimize - trmv - trmvoptimize - trsv - trsvoptimize - supported-types - format-descriptions + :hidden: + + data_types/data_handles + operations/spsv + operations/spmv + operations/spmm + matrix_view + supported-types **Parent topic:** :ref:`onemkl_sparse_linear_algebra` diff --git a/source/elements/oneMKL/source/domains/spblas/supported-types.rst b/source/elements/oneMKL/source/domains/spblas/supported-types.rst index 63cd517ee..8066cae45 100644 --- a/source/elements/oneMKL/source/domains/spblas/supported-types.rst +++ b/source/elements/oneMKL/source/domains/spblas/supported-types.rst @@ -1,23 +1,20 @@ -.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation +.. SPDX-FileCopyrightText: 2024 Intel Corporation .. .. SPDX-License-Identifier: CC-BY-4.0 .. _onemkl_sparse_supported_types: -Supported Types -=============== - +Supported template types +======================== .. container:: - .. container:: tablenoborder - - .. list-table:: + .. list-table:: :header-rows: 1 - * - Data Types + * - Data Types - Integer Types * - ``float`` - ``std::int32_t`` @@ -28,15 +25,4 @@ Supported Types * - ``std::complex`` -   - -General descriptions --------------------- - -.. _onemkl_sparse_matrix_handle_t: - -.. rubric:: matrix_handle_t - :name: matrix_handle_t - -Type for the ``handle`` that can be used to store information about the initial sparse -matrix (represented in a sparse format) and data created/obtained during the analysis -stage to be used in the execution stage. \ No newline at end of file +**Parent topic:** :ref:`onemkl_spblas` diff --git a/source/elements/oneMKL/source/domains/spblas/symv.rst b/source/elements/oneMKL/source/domains/spblas/symv.rst deleted file mode 100644 index d0e7f81bf..000000000 --- a/source/elements/oneMKL/source/domains/spblas/symv.rst +++ /dev/null @@ -1,223 +0,0 @@ -.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation -.. -.. SPDX-License-Identifier: CC-BY-4.0 - -.. _onemkl_sparse_symv: - -symv -==== - -Computes a sparse matrix-dense vector product for a symmetric part of the sparse matrix. - -.. rubric:: Description and Assumptions - -Refer to :ref:`onemkl_sparse_supported_types` for a -list of supported ```` and ````. -The oneapi::mkl::sparse::symv routine computes a sparse matrix-dense vector -product over a symmetric part defined as - -.. math:: - - y \leftarrow \alpha A x + \beta y - - -where: - - -:math:`\alpha` and :math:`\beta` are scalars, :math:`x` and :math:`y` are dense vectors, ``A`` is a sparse matrix. - -.. _onemkl_sparse_symv_buffer: - -symv (Buffer version) ---------------------- - -.. rubric:: Syntax - -.. code-block:: cpp - - namespace oneapi::mkl::sparse { - - void symv (sycl::queue &queue, - oneapi::mkl::uplo uplo_val, - const fp alpha, - oneapi::mkl::sparse::matrix_handle_t A_handle, - sycl::buffer &x, - const fp beta, - sycl::buffer &y); - - } - -.. container:: section - - - .. rubric:: Input Parameters - - - queue - Specifies the SYCL command queue which will be used for SYCL - kernels execution. - - - uplo_val - Specifies which part is to be processed. The possible options are - described in :ref:`onemkl_enum_uplo` enum class. - - - alpha - Specifies the scalar :math:`\alpha`. - - - A_handle - Handle to object containing sparse matrix, :math:`A`. Created using - one of ``oneapi::mkl::sparse::set_csr_data`` or - ``oneapi::mkl::sparse::set_coo_data`` routines. - - - x - SYCL memory object containing an array of size at - least equal to the number of columns of :math:`A` matrix. - - - beta - Specifies the scalar :math:`\beta`. - - - y - SYCL memory object containing an array of size at - least equal to the number of rows of :math:`A` matrix. - - -.. container:: section - - - .. rubric:: Output Parameters - :class: sectiontitle - - y - Overwritten by the updated vector ``y``. - -.. container:: section - - .. rubric:: Throws - :class: sectiontitle - - This routine 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. - - | :ref:`oneapi::mkl::computation_error` - | :ref:`oneapi::mkl::device_bad_alloc` - | :ref:`oneapi::mkl::host_bad_alloc` - | :ref:`oneapi::mkl::invalid_argument` - | :ref:`oneapi::mkl::unimplemented` - | :ref:`oneapi::mkl::uninitialized` - | :ref:`oneapi::mkl::unsupported_device` - -.. _onemkl_sparse_symv_usm: - -symv (USM version) ------------------- - -.. rubric:: Syntax - -.. code-block:: cpp - - namespace oneapi::mkl::sparse { - - sycl::event symv (sycl::queue &queue, - oneapi::mkl::uplo uplo_val, - const fp alpha, - oneapi::mkl::sparse::matrix_handle_t A_handle, - const fp *x, - const fp beta, - fp *y, - const std::vector &dependencies = {}); - - } - -.. container:: section - - - .. rubric:: Input Parameters - - - queue - Specifies the SYCL command queue which will be used for SYCL - kernels execution. - - - uplo_val - Specifies which part is to be processed. The possible options are - described in :ref:`onemkl_enum_uplo` enum class. - - - alpha - Specifies the scalar :math:`\alpha`. - - - A_handle - Handle to object containing sparse matrix, :math:`A`. Created using - one of ``oneapi::mkl::sparse::set_csr_data`` or - ``oneapi::mkl::sparse::set_coo_data`` routines. - - - x - Device-accessible USM object containing an array of size at - least equal to the number of columns of :math:`A` matrix. - - - beta - Specifies the scalar :math:`\beta`. - - - y - Device-accessible USM object containing an array of size at - least equal to the number of rows of :math:`A` matrix. - - dependencies - List of events that oneapi::mkl::sparse::symv routine depends on. - If omitted, defaults to no dependencies. - -.. container:: section - - - .. rubric:: Output Parameters - :class: sectiontitle - - - y - Overwritten by the updated vector ``y``. - -.. container:: section - - .. rubric:: Throws - :class: sectiontitle - - This routine 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. - - | :ref:`oneapi::mkl::computation_error` - | :ref:`oneapi::mkl::device_bad_alloc` - | :ref:`oneapi::mkl::host_bad_alloc` - | :ref:`oneapi::mkl::invalid_argument` - | :ref:`oneapi::mkl::unimplemented` - | :ref:`oneapi::mkl::uninitialized` - | :ref:`oneapi::mkl::unsupported_device` - -.. container:: section - - .. rubric:: Return Values - :class: sectiontitle - - Output event that can be waited upon or added as a - dependency for the completion of symv routine. - - -.. container:: familylinks - - - .. container:: parentlink - - - **Parent topic:** :ref:`onemkl_spblas` diff --git a/source/elements/oneMKL/source/domains/spblas/symvoptimize.rst b/source/elements/oneMKL/source/domains/spblas/symvoptimize.rst deleted file mode 100644 index 1ae6335f0..000000000 --- a/source/elements/oneMKL/source/domains/spblas/symvoptimize.rst +++ /dev/null @@ -1,98 +0,0 @@ -.. SPDX-FileCopyrightText: 2023 Intel Corporation -.. -.. SPDX-License-Identifier: CC-BY-4.0 - -.. _onemkl_sparse_optimize_symv: - -optimize_symv -============= - -Performs internal optimizations for oneapi::mkl::sparse::symv by analyzing -the matrix structure. - -.. rubric:: Description and Assumptions - -The oneapi::mkl::sparse::optimize_symv routine analyzes matrix structure -and performs optimizations. Optimized data is then stored in -the handle. - - -.. rubric:: Syntax - -.. code-block:: cpp - - namespace oneapi::mkl::sparse { - - sycl::event optimize_symv (sycl::queue &queue, - oneapi::mkl::uplo uplo_val, - oneapi::mkl::sparse::matrix_handle_t handle, - const std::vector &dependencies = {}); - } - -.. container:: section - - - .. rubric:: Input Parameters - - - queue - Specifies the SYCL command queue which will be used for SYCL - kernels execution. - - - uplo_val - Specifies which part is to be processed. The possible options are - described in :ref:`onemkl_enum_uplo` enum class. - - - handle - Handle to object containing sparse matrix and other internal - data. Created using one of ``oneapi::mkl::sparse::set_csr_data`` or - ``oneapi::mkl::sparse::set_coo_data`` routines. - - - dependencies - List of events that oneapi::mkl::sparse::optimize_symv routine depends on. - - -.. container:: section - - .. rubric:: Output Parameters - :class: sectiontitle - - handle - Handle might be updated with some internal optimized data by this routine. - -.. container:: section - - .. rubric:: Throws - :class: sectiontitle - - This routine 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. - - | :ref:`oneapi::mkl::computation_error` - | :ref:`oneapi::mkl::device_bad_alloc` - | :ref:`oneapi::mkl::host_bad_alloc` - | :ref:`oneapi::mkl::invalid_argument` - | :ref:`oneapi::mkl::unimplemented` - | :ref:`oneapi::mkl::uninitialized` - | :ref:`oneapi::mkl::unsupported_device` - -.. container:: section - - .. rubric:: Return Values - :class: sectiontitle - - Output event that can be waited upon or added as a - dependency for the completion of optimize_symv routine. - - -.. container:: familylinks - - - .. container:: parentlink - - - **Parent topic:** :ref:`onemkl_spblas` diff --git a/source/elements/oneMKL/source/domains/spblas/trmv.rst b/source/elements/oneMKL/source/domains/spblas/trmv.rst deleted file mode 100644 index 18f627e92..000000000 --- a/source/elements/oneMKL/source/domains/spblas/trmv.rst +++ /dev/null @@ -1,250 +0,0 @@ -.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation -.. -.. SPDX-License-Identifier: CC-BY-4.0 - -.. _onemkl_sparse_trmv: - -trmv -==== - -Computes a sparse matrix-dense vector product over upper or lower triangular matrix parts. - -.. rubric:: Description and Assumptions - -Refer to :ref:`onemkl_sparse_supported_types` for a -list of supported ```` and ````. -The oneapi::mkl::sparse::trmv routine computes a sparse matrix-dense vector -product over a triangular part defined as - -.. math:: - - y \leftarrow \alpha \text{op}(A) x + \beta y - - -where: :math:`alpha` and :math:`beta` are scalars, :math:`x` and :math:`y` are dense vectors, ``A`` is a sparse matrix. - - -.. _onemkl_sparse_trmv_buffer: - -trmv (Buffer version) ---------------------- - -.. rubric:: Syntax - -.. code-block:: cpp - - namespace oneapi::mkl::sparse { - - void trmv (sycl::queue &queue, - oneapi::mkl::uplo uplo_val - oneapi::mkl::transpose transpose_val, - oneapi::mkl::diag diag_val - const fp alpha, - oneapi::mkl::sparse::matrix_handle_t A_handle, - sycl::buffer &x, - const fp beta, - sycl::buffer &y); - - } - -.. container:: section - - - .. rubric:: Input Parameters - - - queue - Specifies the SYCL command queue which will be used for SYCL - kernels execution. - - - uplo_val - Specifies which part is to be processed. The possible options are - described in :ref:`onemkl_enum_uplo` enum class. - - - transpose_val - Specifies operation ``op()`` on input matrix. The possible options - are described in :ref:`onemkl_enum_transpose` enum class. - - - diag_val - Specifies if the diagonal is unit or not. The possible options - are described in :ref:`onemkl_enum_diag` enum class. - - - alpha - Specifies the scalar :math:`\alpha`. - - - A_handle - Handle to object containing sparse matrix, :math:`A`. Created using - one of ``oneapi::mkl::sparse::set_csr_data`` or - ``oneapi::mkl::sparse::set_coo_data`` routines. - - - x - SYCL memory object containing an array of size at least - equal to the number of columns of matrix :math:`\text{op}(A)`. - - - beta - Specifies the scalar :math:`\beta`. - - - y - SYCL memory object containing an array of size at least - equal to the number of rows of matrix :math:`\text{op}(A)`. - - -.. container:: section - - - .. rubric:: Output Parameters - :class: sectiontitle - - - y - Overwritten by the updated vector ``y``. - -.. container:: section - - .. rubric:: Throws - :class: sectiontitle - - This routine 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. - - | :ref:`oneapi::mkl::computation_error` - | :ref:`oneapi::mkl::device_bad_alloc` - | :ref:`oneapi::mkl::host_bad_alloc` - | :ref:`oneapi::mkl::invalid_argument` - | :ref:`oneapi::mkl::unimplemented` - | :ref:`oneapi::mkl::uninitialized` - | :ref:`oneapi::mkl::unsupported_device` - -.. _onemkl_sparse_trmv_usm: - -trmv (USM version) ------------------- - -.. rubric:: Syntax - -.. code-block:: cpp - - namespace oneapi::mkl::sparse { - - sycl::event trmv (sycl::queue &queue, - oneapi::mkl::uplo uplo_val - oneapi::mkl::transpose transpose_val, - oneapi::mkl::diag diag_val - const fp alpha, - oneapi::mkl::sparse::matrix_handle_t A_handle, - const fp *x, - const fp beta, - fp *y - const std::vector &dependencies = {}); - - } - -.. container:: section - - - .. rubric:: Input Parameters - - - queue - Specifies the SYCL command queue which will be used for SYCL - kernels execution. - - - uplo_val - Specifies which part is to be processed. The possible options are - described in :ref:`onemkl_enum_uplo` enum class. - - - transpose_val - Specifies operation ``op()`` on input matrix. The possible options - are described in :ref:`onemkl_enum_transpose` enum class. - - - diag_val - Specifies if the diagonal is unit or not. The possible options - are described in :ref:`onemkl_enum_diag` enum class. - - - alpha - Specifies the scalar :math:`\alpha`. - - - A_handle - Handle to object containing sparse matrix, :math:`A`. Created using - one of ``oneapi::mkl::sparse::set_csr_data`` or - ``oneapi::mkl::sparse::set_coo_data`` routines. - - - x - Device-accessible USM object containing an array of size at least - equal to the number of columns of matrix :math:`\text{op}(A)`. - - - - beta - Specifies the scalar :math:`\beta`. - - - y - Device-accessible USM object containing an array of size at least - equal to the number of rows of matrix :math:`\text{op}(A)`. - - - dependencies - List of events that oneapi::mkl::sparse::trmv routine depends on. - If omitted, defaults to no dependencies. - - - -.. container:: section - - - .. rubric:: Output Parameters - :class: sectiontitle - - - y - Overwritten by the updated vector ``y``. - -.. container:: section - - .. rubric:: Throws - :class: sectiontitle - - This routine 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. - - | :ref:`oneapi::mkl::computation_error` - | :ref:`oneapi::mkl::device_bad_alloc` - | :ref:`oneapi::mkl::host_bad_alloc` - | :ref:`oneapi::mkl::invalid_argument` - | :ref:`oneapi::mkl::unimplemented` - | :ref:`oneapi::mkl::uninitialized` - | :ref:`oneapi::mkl::unsupported_device` - -.. container:: section - - .. rubric:: Return Values - :class: sectiontitle - - Output event that can be waited upon or added as a - dependency for the completion of trmv routine. - - -.. container:: familylinks - - - .. container:: parentlink - - - **Parent topic:** :ref:`onemkl_spblas` diff --git a/source/elements/oneMKL/source/domains/spblas/trmvoptimize.rst b/source/elements/oneMKL/source/domains/spblas/trmvoptimize.rst deleted file mode 100644 index 67bb143e2..000000000 --- a/source/elements/oneMKL/source/domains/spblas/trmvoptimize.rst +++ /dev/null @@ -1,110 +0,0 @@ -.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation -.. -.. SPDX-License-Identifier: CC-BY-4.0 - -.. _onemkl_sparse_optimize_trmv: - -optimize_trmv -============= - -Performs internal optimizations for oneapi::mkl::sparse::trmv by analyzing -the matrix structure. - -.. rubric:: Description and Assumptions - -The oneapi::mkl::sparse::optimize_trmv routine analyzes matrix structure -and performs optimizations. Optimized data is then stored in -the handle. - - -.. rubric:: Syntax - -.. code-block:: cpp - - namespace oneapi::mkl::sparse { - - sycl::event optimize_trmv (sycl::queue &queue, - oneapi::mkl::uplo uplo_val, - oneapi::mkl::transpose transpose_val, - oneapi::mkl::diag diag_val, - oneapi::mkl::sparse::matrix_handle_t handle, - const std::vector &dependencies = {}); - } - -.. container:: section - - - .. rubric:: Input Parameters - - - queue - Specifies the SYCL command queue which will be used for SYCL - kernels execution. - - - uplo_val - Specifies which part is to be processed. The possible options are - described in :ref:`onemkl_enum_uplo` enum class. - - - transpose_val - Specifies operation ``op()`` on input matrix. The possible options - are described in :ref:`onemkl_enum_transpose` enum class. - - - diag_val - Specifies if the diagonal is unit or not. The possible options - are described in :ref:`onemkl_enum_diag` enum class. - - - handle - Handle to object containing sparse matrix and other internal - data. Created using one of ``oneapi::mkl::sparse::set_csr_data`` or - ``oneapi::mkl::sparse::set_coo_data`` routines. - - - dependencies - List of events that oneapi::mkl::sparse::optimize_trmv routine depends on. - - -.. container:: section - - .. rubric:: Output Parameters - :class: sectiontitle - - handle - Handle might be updated with some internal optimized data by this routine. - -.. container:: section - - .. rubric:: Throws - :class: sectiontitle - - This routine 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. - - | :ref:`oneapi::mkl::computation_error` - | :ref:`oneapi::mkl::device_bad_alloc` - | :ref:`oneapi::mkl::host_bad_alloc` - | :ref:`oneapi::mkl::invalid_argument` - | :ref:`oneapi::mkl::unimplemented` - | :ref:`oneapi::mkl::uninitialized` - | :ref:`oneapi::mkl::unsupported_device` - -.. container:: section - - .. rubric:: Return Values - :class: sectiontitle - - Output event that can be waited upon or added as a - dependency for the completion of optimize_trmv routine. - - -.. container:: familylinks - - - .. container:: parentlink - - - **Parent topic:** :ref:`onemkl_spblas` diff --git a/source/elements/oneMKL/source/domains/spblas/trsv.rst b/source/elements/oneMKL/source/domains/spblas/trsv.rst deleted file mode 100644 index fe91e88f2..000000000 --- a/source/elements/oneMKL/source/domains/spblas/trsv.rst +++ /dev/null @@ -1,217 +0,0 @@ -.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation -.. -.. SPDX-License-Identifier: CC-BY-4.0 - -.. _onemkl_sparse_trsv: - -trsv -==== - -Solves a system of linear equations for a triangular sparse matrix. - -.. rubric:: Description and Assumptions - -Refer to :ref:`onemkl_sparse_supported_types` for a -list of supported ```` and ````. -The oneapi::mkl::sparse::trsv routine solves a system of linear equations -for a square matrix: - - -.. math:: - - \text{op}(A) y \leftarrow x - -where: ``A`` is a triangular sparse matrix of size ``m`` rows by -``m`` columns, op is a matrix modifier for matrix ``A``, ``x`` and ``y`` are dense vectors of length at least -``m``. - -.. _onemkl_sparse_trsv_buffer: - -trsv (Buffer version) ---------------------- - -.. rubric:: Syntax - -.. code-block:: cpp - - namespace oneapi::mkl::sparse { - - void trsv (sycl::queue &queue, - oneapi::mkl::uplo uplo_val - oneapi::mkl::transpose transpose_val, - oneapi::mkl::diag diag_val - oneapi::mkl::sparse::matrix_handle_t A_handle, - sycl::buffer &x, - sycl::buffer &y); - - } - -.. container:: section - - - .. rubric:: Input Parameters - - - queue - Specifies the SYCL command queue which will be used for SYCL - kernels execution. - - - uplo_val - Specifies which part is to be processed. The possible options are - described in :ref:`onemkl_enum_uplo` enum class. - - - transpose_val - Specifies operation ``op()`` on input matrix. The possible options - are described in :ref:`onemkl_enum_transpose` enum class. - - - diag_val - Specifies if the diagonal is unit or not. The possible options - are described in :ref:`onemkl_enum_diag` enum class. - - - A_handle - Handle to object containing sparse matrix, :math:`A`. Created using - one of ``oneapi::mkl::sparse::set_csr_data`` or - ``oneapi::mkl::sparse::set_coo_data`` routines. - - - x - SYCL memory object containing an array of size at least - equal to the number of columns of matrix :math:`\text{op}(A)`. - - -.. container:: section - - - .. rubric:: Output Parameters - :class: sectiontitle - - y - SYCL memory object containing an array of size at least ``nRows`` filled with the solution to the system of linear equations. - -.. container:: section - - .. rubric:: Throws - :class: sectiontitle - - This routine 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. - - | :ref:`oneapi::mkl::computation_error` - | :ref:`oneapi::mkl::device_bad_alloc` - | :ref:`oneapi::mkl::host_bad_alloc` - | :ref:`oneapi::mkl::invalid_argument` - | :ref:`oneapi::mkl::unimplemented` - | :ref:`oneapi::mkl::uninitialized` - | :ref:`oneapi::mkl::unsupported_device` - -.. _onemkl_sparse_trsv_usm: - -trsv (USM version) ------------------- - -.. rubric:: Syntax - -.. code-block:: cpp - - namespace oneapi::mkl::sparse { - - sycl::event trsv (sycl::queue &queue, - oneapi::mkl::uplo uplo_val - oneapi::mkl::transpose transpose_val, - oneapi::mkl::diag diag_val - oneapi::mkl::sparse::matrix_handle_t A_handle, - const fp *x, - fp *y - const std::vector &dependencies = {}); - - } - -.. container:: section - - - .. rubric:: Input Parameters - - - queue - Specifies the SYCL command queue which will be used for SYCL - kernels execution. - - - uplo_val - Specifies which part is to be processed. The possible options are - described in :ref:`onemkl_enum_uplo` enum class. - - - transpose_val - Specifies operation ``op()`` on input matrix. The possible options - are described in :ref:`onemkl_enum_transpose` enum class. - - - diag_val - Specifies if the diagonal is unit or not. The possible options - are described in :ref:`onemkl_enum_diag` enum class. - - - A_handle - Handle to object containing sparse matrix, :math:`A`. Created using - one of ``oneapi::mkl::sparse::set_csr_data`` or - ``oneapi::mkl::sparse::set_coo_data`` routines. - - - x - Device-accessible USM object containing an array of size at least - equal to the number of columns of matrix :math:`\text{op}(A)`. - - - dependencies - List of events that oneapi::mkl::sparse::trmv routine depends on. - If omitted, defaults to no dependencies. - - - -.. container:: section - - - .. rubric:: Output Parameters - :class: sectiontitle - - y - Device-accessible USM object containing an array of size at least ``nRows`` filled with the solution to the system of linear equations. - -.. container:: section - - .. rubric:: Throws - :class: sectiontitle - - This routine 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. - - | :ref:`oneapi::mkl::computation_error` - | :ref:`oneapi::mkl::device_bad_alloc` - | :ref:`oneapi::mkl::host_bad_alloc` - | :ref:`oneapi::mkl::invalid_argument` - | :ref:`oneapi::mkl::unimplemented` - | :ref:`oneapi::mkl::uninitialized` - | :ref:`oneapi::mkl::unsupported_device` - -.. container:: section - - .. rubric:: Return Values - :class: sectiontitle - - Output event that can be waited upon or added as a - dependency for the completion of trmv routine. - -.. container:: familylinks - - - .. container:: parentlink - - - **Parent topic:** :ref:`onemkl_spblas` diff --git a/source/elements/oneMKL/source/domains/spblas/trsvoptimize.rst b/source/elements/oneMKL/source/domains/spblas/trsvoptimize.rst deleted file mode 100644 index 805f3308e..000000000 --- a/source/elements/oneMKL/source/domains/spblas/trsvoptimize.rst +++ /dev/null @@ -1,111 +0,0 @@ -.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation -.. -.. SPDX-License-Identifier: CC-BY-4.0 - -.. _onemkl_sparse_optimize_trsv: - -optimize_trsv -============= - -Performs internal optimizations for oneapi::mkl::sparse::trsv by analyzing -the matrix structure. - -.. rubric:: Description and Assumptions - -The oneapi::mkl::sparse::optimize_trsv routine analyzes matrix structure -and performs optimizations. Optimized data is then stored in -the handle. - - -.. rubric:: Syntax - - -.. code-block:: cpp - - namespace oneapi::mkl::sparse { - - sycl::event optimize_trsv (sycl::queue &queue, - oneapi::mkl::uplo uplo_val, - oneapi::mkl::transpose transpose_val, - oneapi::mkl::diag diag_val, - oneapi::mkl::sparse::matrix_handle_t handle, - const std::vector &dependencies = {}); - } - -.. container:: section - - - .. rubric:: Input Parameters - - - queue - Specifies the SYCL command queue which will be used for SYCL - kernels execution. - - - uplo_val - Specifies which part is to be processed. The possible options are - described in :ref:`onemkl_enum_uplo` enum class. - - - transpose_val - Specifies operation ``op()`` on input matrix. The possible options - are described in :ref:`onemkl_enum_transpose` enum class. - - - diag_val - Specifies if the diagonal is unit or not. The possible options - are described in :ref:`onemkl_enum_diag` enum class. - - - handle - Handle to object containing sparse matrix and other internal - data. Created using one of ``oneapi::mkl::sparse::set_csr_data`` or - ``oneapi::mkl::sparse::set_coo_data`` routines. - - - dependencies - List of events that oneapi::mkl::sparse::optimize_trsv routine depends on. - - -.. container:: section - - .. rubric:: Output Parameters - :class: sectiontitle - - handle - Handle might be updated with some internal optimized data by this routine. - -.. container:: section - - .. rubric:: Throws - :class: sectiontitle - - This routine 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. - - | :ref:`oneapi::mkl::computation_error` - | :ref:`oneapi::mkl::device_bad_alloc` - | :ref:`oneapi::mkl::host_bad_alloc` - | :ref:`oneapi::mkl::invalid_argument` - | :ref:`oneapi::mkl::unimplemented` - | :ref:`oneapi::mkl::uninitialized` - | :ref:`oneapi::mkl::unsupported_device` - -.. container:: section - - .. rubric:: Return Values - :class: sectiontitle - - Output event that can be waited upon or added as a - dependency for the completion of optimize_trsv routine. - - -.. container:: familylinks - - - .. container:: parentlink - - - **Parent topic:** :ref:`onemkl_spblas` From 3e5c25833e31c310614c2e40bb038704f81c3d53 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Tue, 5 Mar 2024 17:30:50 +0000 Subject: [PATCH 02/52] Reword high level sparse_blas domain page --- .../domains/sparse_linear_algebra.inc.rst | 37 +++++++------------ 1 file changed, 14 insertions(+), 23 deletions(-) diff --git a/source/elements/oneMKL/source/domains/sparse_linear_algebra.inc.rst b/source/elements/oneMKL/source/domains/sparse_linear_algebra.inc.rst index 27182437a..37af34c47 100644 --- a/source/elements/oneMKL/source/domains/sparse_linear_algebra.inc.rst +++ b/source/elements/oneMKL/source/domains/sparse_linear_algebra.inc.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation +.. SPDX-FileCopyrightText: 2024 Intel Corporation .. .. SPDX-License-Identifier: CC-BY-4.0 @@ -9,30 +9,21 @@ Sparse Linear Algebra .. container:: + The oneAPI Math Kernel Library provides a Data Parallel C++ interface to some + of the Sparse Linear Algebra routines. - The oneAPI Math Kernel Library provides a Data Parallel C++ interface - to some of the Sparse Linear Algebra routines. - - :ref:`onemkl_spblas` provides basic operations on sparse vectors and matrices, and - separates them into two stages: analysis - (also called inspector stage or optimize stage) and execution. For a given matrix, - the analysis would typically be called one time and the execution may be called - multiple times. During the analysis stage, the API inspects the matrix properties - including size, sparsity pattern and available parallelism and can apply matrix - format or structure changes to enable a more optimized algorithm. - In the execution stage, multiple routine calls can take advantage of the analysis - stage data in order to improve performance. - -.. TODO: Reword and remove onemkl_sparse_matrix_handle_t - - In order to save information in between calls to Sparse BLAS computation routines, - the ``onemkl_sparse_matrix_handle_t`` type is introduced, that is essentially - an opaque pointer, used to store data related to initial sparse matrix - and data obtained during analysis stage. - + :ref:`onemkl_spblas` provides basic operations on sparse vectors and + matrices, and separates them into three stages: query of the external + workspace size, optimization stage and execution. For a given configuration, + the first two stages would typically be called once and the execution may be + called multiple times. During the optimization stage, the API inspects the + matrix properties including size, sparsity pattern and available parallelism + and can apply matrix format or structure changes to enable a more optimized + algorithm. In the execution stage, multiple routine calls can take advantage + of the optimization stage data in order to improve performance. .. toctree:: - :hidden: + :hidden: - spblas/spblas.rst + spblas/spblas.rst From 0b92a224ada93298646b977e86d49841a03184a2 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Tue, 5 Mar 2024 17:45:21 +0000 Subject: [PATCH 03/52] Fix set_dense_vector_data alignment --- .../source/domains/spblas/data_types/set_dense_vector_data.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst index 7442c4b3d..44b7189f2 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst @@ -94,7 +94,7 @@ set_dense_vector_data (USM version) namespace oneapi::mkl::sparse { template - void set_dense_vector_data (sycl::queue &queue, + void set_dense_vector_data (sycl::queue &queue, oneapi::mkl::sparse::dense_vector_handle_t dvhandle, std::int64_t size, fpType *val); From ce62ad3857a056bb4260a025af948e25f27c3633 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Thu, 7 Mar 2024 14:36:07 +0000 Subject: [PATCH 04/52] Rename template types to dataType and indexType --- .../spblas/data_types/create_coo_matrix.rst | 24 +++++------ .../spblas/data_types/create_csr_matrix.rst | 24 +++++------ .../spblas/data_types/create_dense_matrix.rst | 12 +++--- .../spblas/data_types/create_dense_vector.rst | 12 +++--- .../spblas/data_types/set_coo_matrix_data.rst | 24 +++++------ .../spblas/data_types/set_csr_matrix_data.rst | 24 +++++------ .../data_types/set_dense_matrix_data.rst | 12 +++--- .../data_types/set_dense_vector_data.rst | 12 +++--- .../source/domains/spblas/supported-types.rst | 40 +++++++++++-------- 9 files changed, 95 insertions(+), 89 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst index 9d3320a0d..cc0119b7e 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst @@ -50,16 +50,16 @@ create_coo_matrix (Buffer version) namespace oneapi::mkl::sparse { - template + template void create_coo_matrix (sycl::queue &queue, oneapi::mkl::sparse::matrix_handle_t *p_smhandle, std::int64_t num_rows, std::int64_t num_cols, std::int64_t nnz, index_base index, - sycl::buffer &row_ind, - sycl::buffer &col_ind, - sycl::buffer &val); + sycl::buffer &row_ind, + sycl::buffer &col_ind, + sycl::buffer &val); } @@ -67,10 +67,10 @@ create_coo_matrix (Buffer version) .. rubric:: Template parameters - fpType + dataType See :ref:`supported template types`. - intType + indexType See :ref:`supported template types`. .. container:: section @@ -148,16 +148,16 @@ create_coo_matrix (USM version) namespace oneapi::mkl::sparse { - template + template void create_coo_matrix (sycl::queue &queue, oneapi::mkl::sparse::matrix_handle_t *p_smhandle, std::int64_t num_rows, std::int64_t num_cols, std::int64_t nnz, index_base index, - intType *row_ind, - intType *col_ind, - fpType *val); + indexType *row_ind, + indexType *col_ind, + dataType *val); } @@ -165,10 +165,10 @@ create_coo_matrix (USM version) .. rubric:: Template parameters - fpType + dataType See :ref:`supported template types`. - intType + indexType See :ref:`supported template types`. .. container:: section diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst index 52c449b60..4540425d3 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst @@ -50,16 +50,16 @@ create_csr_matrix (Buffer version) namespace oneapi::mkl::sparse { - template + template void create_csr_matrix (sycl::queue &queue, oneapi::mkl::sparse::matrix_handle_t *p_smhandle, std::int64_t num_rows, std::int64_t num_cols, std::int64_t nnz, index_base index, - sycl::buffer &row_ptr, - sycl::buffer &col_ind, - sycl::buffer &val); + sycl::buffer &row_ptr, + sycl::buffer &col_ind, + sycl::buffer &val); } @@ -67,10 +67,10 @@ create_csr_matrix (Buffer version) .. rubric:: Template parameters - fpType + dataType See :ref:`supported template types`. - intType + indexType See :ref:`supported template types`. .. container:: section @@ -147,16 +147,16 @@ create_csr_matrix (USM version) namespace oneapi::mkl::sparse { - template + template void create_csr_matrix (sycl::queue &queue, oneapi::mkl::sparse::matrix_handle_t *p_smhandle, std::int64_t num_rows, std::int64_t num_cols, std::int64_t nnz, index_base index, - intType *row_ptr, - intType *col_ind, - fpType *val); + indexType *row_ptr, + indexType *col_ind, + dataType *val); } @@ -164,10 +164,10 @@ create_csr_matrix (USM version) .. rubric:: Template parameters - fpType + dataType See :ref:`supported template types`. - intType + indexType See :ref:`supported template types`. .. container:: section diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_matrix.rst index 752c8da5a..2f079a499 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_matrix.rst @@ -34,14 +34,14 @@ create_dense_matrix (Buffer version) namespace oneapi::mkl::sparse { - template + template void create_dense_matrix (sycl::queue &queue, oneapi::mkl::sparse::dense_matrix_handle_t *p_dmhandle, std::int64_t num_rows, std::int64_t num_cols, std::int64_t ld, layout dense_layout, - sycl::buffer &val); + sycl::buffer &val); } @@ -49,7 +49,7 @@ create_dense_matrix (Buffer version) .. rubric:: Template parameters - fpType + dataType See :ref:`supported template types`. .. container:: section @@ -117,14 +117,14 @@ create_dense_matrix (USM version) namespace oneapi::mkl::sparse { - template + template void create_dense_matrix (sycl::queue &queue, oneapi::mkl::sparse::dense_matrix_handle_t *p_dmhandle, std::int64_t num_rows, std::int64_t num_cols, std::int64_t ld, layout dense_layout, - fpType *val); + dataType *val); } @@ -132,7 +132,7 @@ create_dense_matrix (USM version) .. rubric:: Template parameters - fpType + dataType See :ref:`supported template types`. .. container:: section diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_vector.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_vector.rst index e4d2f88a5..d71d8d007 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_vector.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_vector.rst @@ -34,11 +34,11 @@ create_dense_vector (Buffer version) namespace oneapi::mkl::sparse { - template + template void create_dense_vector (sycl::queue &queue, oneapi::mkl::sparse::dense_vector_handle_t *p_dvhandle, std::int64_t size, - sycl::buffer &val); + sycl::buffer &val); } @@ -46,7 +46,7 @@ create_dense_vector (Buffer version) .. rubric:: Template parameters - fpType + dataType See :ref:`supported template types`. .. container:: section @@ -102,11 +102,11 @@ create_dense_vector (USM version) namespace oneapi::mkl::sparse { - template + template void create_dense_vector (sycl::queue &queue, oneapi::mkl::sparse::dense_vector_handle_t *p_dvhandle, std::int64_t size, - fpType *val); + dataType *val); } @@ -114,7 +114,7 @@ create_dense_vector (USM version) .. rubric:: Template parameters - fpType + dataType See :ref:`supported template types`. .. container:: section diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst index 6828c7b82..348c4a829 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst @@ -34,16 +34,16 @@ set_coo_matrix_data (Buffer version) namespace oneapi::mkl::sparse { - template + template void set_coo_matrix_data (sycl::queue &queue, oneapi::mkl::sparse::matrix_handle_t smhandle, std::int64_t num_rows, std::int64_t num_cols, std::int64_t nnz, index_base index, - sycl::buffer &row_ind, - sycl::buffer &col_ind, - sycl::buffer &val); + sycl::buffer &row_ind, + sycl::buffer &col_ind, + sycl::buffer &val); } @@ -51,11 +51,11 @@ set_coo_matrix_data (Buffer version) .. rubric:: Template parameters - fpType + dataType See :ref:`supported template types`. Can be a different type than what was used when creating the ``matrix_handle_t``. - intType + indexType See :ref:`supported template types`. Can be a different type than what was used when creating the ``matrix_handle_t``. @@ -124,16 +124,16 @@ set_coo_matrix_data (USM version) namespace oneapi::mkl::sparse { - template + template void set_coo_matrix_data (sycl::queue &queue, oneapi::mkl::sparse::matrix_handle_t smhandle, std::int64_t num_rows, std::int64_t num_cols, std::int64_t nnz, index_base index, - intType *row_ind, - intType *col_ind, - fpType *val); + indexType *row_ind, + indexType *col_ind, + dataType *val); } @@ -141,11 +141,11 @@ set_coo_matrix_data (USM version) .. rubric:: Template parameters - fpType + dataType See :ref:`supported template types`. Can be a different type than what was used when creating the ``matrix_handle_t``. - intType + indexType See :ref:`supported template types`. Can be a different type than what was used when creating the ``matrix_handle_t``. diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst index 962a0658a..bbd461c2f 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst @@ -34,16 +34,16 @@ set_csr_matrix_data (Buffer version) namespace oneapi::mkl::sparse { - template + template void set_csr_matrix_data (sycl::queue &queue, oneapi::mkl::sparse::matrix_handle_t smhandle, std::int64_t num_rows, std::int64_t num_cols, std::int64_t nnz, index_base index, - sycl::buffer &row_ptr, - sycl::buffer &col_ind, - sycl::buffer &val); + sycl::buffer &row_ptr, + sycl::buffer &col_ind, + sycl::buffer &val); } @@ -51,11 +51,11 @@ set_csr_matrix_data (Buffer version) .. rubric:: Template parameters - fpType + dataType See :ref:`supported template types`. Can be a different type than what was used when creating the ``matrix_handle_t``. - intType + indexType See :ref:`supported template types`. Can be a different type than what was used when creating the ``matrix_handle_t``. @@ -123,16 +123,16 @@ set_csr_matrix_data (USM version) namespace oneapi::mkl::sparse { - template + template void set_csr_matrix_data (sycl::queue &queue, oneapi::mkl::sparse::matrix_handle_t smhandle, std::int64_t num_rows, std::int64_t num_cols, std::int64_t nnz, index_base index, - intType *row_ptr, - intType *col_ind, - fpType *val); + indexType *row_ptr, + indexType *col_ind, + dataType *val); } @@ -140,11 +140,11 @@ set_csr_matrix_data (USM version) .. rubric:: Template parameters - fpType + dataType See :ref:`supported template types`. Can be a different type than what was used when creating the ``matrix_handle_t``. - intType + indexType See :ref:`supported template types`. Can be a different type than what was used when creating the ``matrix_handle_t``. diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst index 526d33e1d..705359c71 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst @@ -34,14 +34,14 @@ set_dense_matrix_data (Buffer version) namespace oneapi::mkl::sparse { - template + template void set_dense_matrix_data (sycl::queue &queue, oneapi::mkl::sparse::dense_matrix_handle_t dmhandle, std::int64_t num_rows, std::int64_t num_cols, std::int64_t ld, layout dense_layout, - sycl::buffer &val); + sycl::buffer &val); } @@ -49,7 +49,7 @@ set_dense_matrix_data (Buffer version) .. rubric:: Template parameters - fpType + dataType See :ref:`supported template types`. Can be a different type than what was used when creating the ``dense_matrix_handle_t``. @@ -109,14 +109,14 @@ set_dense_matrix_data (USM version) namespace oneapi::mkl::sparse { - template + template void set_dense_matrix_data (sycl::queue &queue, oneapi::mkl::sparse::dense_matrix_handle_t dmhandle, std::int64_t num_rows, std::int64_t num_cols, std::int64_t ld, layout dense_layout, - fpType *val); + dataType *val); } @@ -124,7 +124,7 @@ set_dense_matrix_data (USM version) .. rubric:: Template parameters - fpType + dataType See :ref:`supported template types`. Can be a different type than what was used when creating the ``dense_matrix_handle_t``. diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst index 44b7189f2..6a1c1db75 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst @@ -34,11 +34,11 @@ set_dense_vector_data (Buffer version) namespace oneapi::mkl::sparse { - template + template void set_dense_vector_data (sycl::queue &queue, oneapi::mkl::sparse::dense_vector_handle_t dvhandle, std::int64_t size, - sycl::buffer &val); + sycl::buffer &val); } @@ -46,7 +46,7 @@ set_dense_vector_data (Buffer version) .. rubric:: Template parameters - fpType + dataType See :ref:`supported template types`. Can be a different type than what was used when creating the ``dense_vector_handle_t``. @@ -93,11 +93,11 @@ set_dense_vector_data (USM version) namespace oneapi::mkl::sparse { - template + template void set_dense_vector_data (sycl::queue &queue, oneapi::mkl::sparse::dense_vector_handle_t dvhandle, std::int64_t size, - fpType *val); + dataType *val); } @@ -105,7 +105,7 @@ set_dense_vector_data (USM version) .. rubric:: Template parameters - fpType + dataType See :ref:`supported template types`. Can be a different type than what was used when creating the ``dense_vector_handle_t``. diff --git a/source/elements/oneMKL/source/domains/spblas/supported-types.rst b/source/elements/oneMKL/source/domains/spblas/supported-types.rst index 8066cae45..858f1a699 100644 --- a/source/elements/oneMKL/source/domains/spblas/supported-types.rst +++ b/source/elements/oneMKL/source/domains/spblas/supported-types.rst @@ -7,22 +7,28 @@ Supported template types ======================== -.. container:: - - .. container:: tablenoborder - - .. list-table:: - :header-rows: 1 - - * - Data Types - - Integer Types - * - ``float`` - - ``std::int32_t`` - * - ``double`` - - ``std::int64_t`` - * - ``std::complex`` - -   - * - ``std::complex`` - -   +.. container:: tablenoborder + + .. list-table:: + :header-rows: 1 + + * - Data Types ```` + - Integer Types ```` + * - ``float`` + - ``std::int32_t`` + * - ``double`` + - ``std::int64_t`` + * - ``std::complex`` + -   + * - ``std::complex`` + -   + +``dataType`` is used to describe the precision (i.e. number of bits) and domain +(i.e. real or complex) of the :ref:`data handles ` +and the operations using them. + +``indexType`` is used to describe the range of integer types such as indices, +offsets or sizes of the :ref:`data handles ` and the +operations using them. **Parent topic:** :ref:`onemkl_spblas` From 52a3a6e3dedc31bf3c15dcfe41058665e564d7bb Mon Sep 17 00:00:00 2001 From: Romain Biessy Date: Mon, 11 Mar 2024 11:47:52 +0000 Subject: [PATCH 05/52] Add comma Co-authored-by: HJA Bird <9040797+hjabird@users.noreply.github.com> --- .../oneMKL/source/domains/sparse_linear_algebra.inc.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/elements/oneMKL/source/domains/sparse_linear_algebra.inc.rst b/source/elements/oneMKL/source/domains/sparse_linear_algebra.inc.rst index 37af34c47..3dd6f871f 100644 --- a/source/elements/oneMKL/source/domains/sparse_linear_algebra.inc.rst +++ b/source/elements/oneMKL/source/domains/sparse_linear_algebra.inc.rst @@ -17,7 +17,7 @@ Sparse Linear Algebra workspace size, optimization stage and execution. For a given configuration, the first two stages would typically be called once and the execution may be called multiple times. During the optimization stage, the API inspects the - matrix properties including size, sparsity pattern and available parallelism + matrix properties including size, sparsity pattern and available parallelism, and can apply matrix format or structure changes to enable a more optimized algorithm. In the execution stage, multiple routine calls can take advantage of the optimization stage data in order to improve performance. From c272e3fdbe7f91d8a43d05fe102298ee390ac229 Mon Sep 17 00:00:00 2001 From: Romain Biessy Date: Mon, 11 Mar 2024 11:48:21 +0000 Subject: [PATCH 06/52] Capitalize acronym Co-authored-by: HJA Bird <9040797+hjabird@users.noreply.github.com> --- .../source/domains/spblas/data_types/format-descriptions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/format-descriptions.rst b/source/elements/oneMKL/source/domains/spblas/data_types/format-descriptions.rst index 9483209b9..dd00a338e 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/format-descriptions.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/format-descriptions.rst @@ -9,7 +9,7 @@ Sparse storage formats There are a variety of matrix storage formats available for representing sparse matrices. Two popular formats are the coordinate (COO) format, and the -compressed sparse row (CSR) format. +Compressed Sparse Row (CSR) format. .. container:: section From e6811a4e2822514872112b1b3d78ebf1f6ef99f9 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Mon, 11 Mar 2024 11:59:51 +0000 Subject: [PATCH 07/52] Remove / --- .../source/domains/spblas/data_types/create_coo_matrix.rst | 2 +- .../source/domains/spblas/data_types/create_csr_matrix.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst index cc0119b7e..42987282b 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst @@ -26,7 +26,7 @@ the number of non-zero elements in the sparse matrix as an argument. However, in certain math operations where the output is a sparse matrix, e.g., sparse matrix addition (sparse matrix + sparse matrix = sparse matrix), and multiplication of two sparse matrices, the number of non-zero elements in the output sparse matrix -is not known in advance and must be calculated as part of the operation/API. +is not known in advance and must be calculated as part of the operation API. Such APIs are currently not a part of the current oneMKL Specification, but will be added in the future. Therefore, it is important for the ``create_coo_matrix`` API to be able to handle multiple calls to build the sparse matrix as function diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst index 4540425d3..cd186589a 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst @@ -26,7 +26,7 @@ the number of non-zero elements in the sparse matrix as an argument. However, in certain math operations where the output is a sparse matrix, e.g., sparse matrix addition (sparse matrix + sparse matrix = sparse matrix), and multiplication of two sparse matrices, the number of non-zero elements in the output sparse matrix -is not known in advance and must be calculated as part of the operation/API. +is not known in advance and must be calculated as part of the operation API. Such APIs are currently not a part of the current oneMKL Specification, but will be added in the future. Therefore, it is important for the ``create_csr_matrix`` API to be able to handle multiple calls to build the sparse matrix as function From 96bee855d4da59333356e171c99f1d988e6239d9 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Mon, 11 Mar 2024 14:46:45 +0000 Subject: [PATCH 08/52] Clarify non-zero entries --- .../spblas/data_types/format-descriptions.rst | 21 +++++++++++-------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/format-descriptions.rst b/source/elements/oneMKL/source/domains/spblas/data_types/format-descriptions.rst index dd00a338e..63faeb15b 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/format-descriptions.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/format-descriptions.rst @@ -11,6 +11,11 @@ There are a variety of matrix storage formats available for representing sparse matrices. Two popular formats are the coordinate (COO) format, and the Compressed Sparse Row (CSR) format. +In this specification, "non-zero" elements or "non-zero" entries refer to +explicitly defined elements or entries which may take any value supported by the +the `:ref:data type`. Undefined elements or +entries are implicitly zeros. + .. container:: section .. _onemkl_sparse_coo: @@ -18,8 +23,8 @@ Compressed Sparse Row (CSR) format. .. rubric:: COO The COO format is the simplest sparse matrix format, represented by three - arrays, ``row_ind``, ``col_ind`` and ``val``, and an ``index`` parameter. - Each non-zero element, ``i`` in the sparse matrix is represented by its row + arrays, ``row_ind``, ``col_ind`` and ``val``, and an ``index`` parameter. The + ``i``-th defined element in the sparse matrix is represented by its row index, column index, and value, that is, (``row_ind[i]``, ``col_ind[i]``, ``val[i]``). The entries need not be in a sorted order. @@ -32,9 +37,8 @@ Compressed Sparse Row (CSR) format. * - num_cols - Number of columns in the sparse matrix. * - nnz - - Number of non-zero entries in the sparse matrix (which may include - explicit zeros). This is also the length of the ``row_ind``, - ``col_ind`` and ``val`` arrays. + - Number of non-zero entries in the sparse matrix. This is also the + length of the ``row_ind``, ``col_ind`` and ``val`` arrays. * - index - Parameter that is used to specify whether the matrix has zero or one-based indexing. @@ -97,9 +101,8 @@ one-based indexing): * - num_cols - Number of columns in the sparse matrix. * - nnz - - Number of non-zero entries in the sparse matrix (which may include - explicit zeros). This is also the length of the ``col_ind`` and - ``val`` arrays. + - Number of non-zero entries in the sparse matrix. This is also the + length of the ``col_ind`` and ``val`` arrays. * - index - Parameter that is used to specify whether the matrix has zero or one-based indexing. @@ -117,7 +120,7 @@ one-based indexing): ``val`` array that is first non-zero element in a row ``j`` of ``A``. Note that this position is equal to ``row_ptr[j] - index``. Last element of the ``row_ptr`` array (``row_ptr[num_rows]``) - stores the sum of, number of nonzero elements and ``index`` + stores the sum of, number of non-zero elements and ``index`` (``nnz + index``). A sparse matrix can be represented in a CSR format in a following way (assuming From 2545e7b8d69cc51f3d347a3070b4f2dbddbc97fa Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Mon, 11 Mar 2024 15:43:35 +0000 Subject: [PATCH 09/52] Add requirements on workspace alignment --- .../elements/oneMKL/source/domains/spblas/operations/spmm.rst | 3 ++- .../elements/oneMKL/source/domains/spblas/operations/spmv.rst | 3 ++- .../elements/oneMKL/source/domains/spblas/operations/spsv.rst | 3 ++- 3 files changed, 6 insertions(+), 3 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst index 3f60a203f..246667553 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst @@ -349,7 +349,8 @@ spmm ``temp_buffer_size`` bytes. If it is a buffer, its lifetime is extended until the :ref:`spmm descriptor` is released. If it is a USM pointer, it must not be free'd until ``spmm`` has completed. - The data must be accessible on the device. + The data must be accessible on the device and the address aligned on the + size of the handles' data type. dependencies List of events to depend on before starting asynchronous tasks that access diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst index 20495be5f..1a0ea12b6 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst @@ -327,7 +327,8 @@ spmv ``temp_buffer_size`` bytes. If it is a buffer, its lifetime is extended until the :ref:`spmv descriptor` is released. If it is a USM pointer, it must not be free'd until ``spmv`` has completed. - The data must be accessible on the device. + The data must be accessible on the device and the address aligned on the + size of the handles' data type. dependencies List of events to depend on before starting asynchronous tasks that access diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst index 2e1553e13..71af35448 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst @@ -289,7 +289,8 @@ spsv ``temp_buffer_size`` bytes. If it is a buffer, its lifetime is extended until the :ref:`spsv descriptor` is released. If it is a USM pointer, it must not be free'd until ``spsv`` has completed. - The data must be accessible on the device. + The data must be accessible on the device and the address aligned on the + size of the handles' data type. dependencies List of events to depend on before starting asynchronous tasks that access From 6db751416a75e77f108e66dcffb672d5f3f5f95c Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Mon, 11 Mar 2024 15:53:04 +0000 Subject: [PATCH 10/52] Clarify alpha and beta type --- .../oneMKL/source/domains/spblas/operations/spmm.rst | 6 ++++-- .../oneMKL/source/domains/spblas/operations/spmv.rst | 6 ++++-- .../oneMKL/source/domains/spblas/operations/spsv.rst | 3 ++- 3 files changed, 10 insertions(+), 5 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst index 246667553..9fe54db15 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst @@ -316,7 +316,8 @@ spmm alpha Host or USM pointer representing :math:`\alpha`. The USM allocation can be - on the host or device. + on the host or device. Must be of the same type than the handles' data + type. A_view Specifies which part of the handle should be read as described by @@ -330,7 +331,8 @@ spmm beta Host or USM pointer representing :math:`\beta`. The USM allocation can be - on the host or device. + on the host or device. Must be of the same type than the handles' data + type. C_handle Dense matrix handle object representing :math:`C`. diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst index 1a0ea12b6..ed3768f5a 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst @@ -294,7 +294,8 @@ spmv alpha Host or USM pointer representing :math:`\alpha`. The USM allocation can be - on the host or device. + on the host or device. Must be of the same type than the handles' data + type. A_view Specifies which part of the handle should be read as described by @@ -308,7 +309,8 @@ spmv beta Host or USM pointer representing :math:`\beta`. The USM allocation can be - on the host or device. + on the host or device. Must be of the same type than the handles' data + type. y_handle Dense vector handle object representing :math:`y`. diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst index 71af35448..8a178de28 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst @@ -260,7 +260,8 @@ spsv alpha Host or USM pointer representing :math:`\alpha`. The USM allocation can be - on the host or device. + on the host or device. Must be of the same type than the handles' data + type. A_view Specifies which part of the handle should be read as described by From fda672d157c8935758fceb8667a9b0e512601042 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Mon, 11 Mar 2024 16:21:23 +0000 Subject: [PATCH 11/52] Do not italicise T and H --- .../elements/oneMKL/source/domains/spblas/operations/spmm.rst | 4 ++-- .../elements/oneMKL/source/domains/spblas/operations/spmv.rst | 4 ++-- .../elements/oneMKL/source/domains/spblas/operations/spsv.rst | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst index 9fe54db15..f9fbcf0ed 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst @@ -25,8 +25,8 @@ matrix modifier for :math:`A` and :math:`B` using the following description: .. math:: \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} + A^\mathsf{T},& \text{oneapi::mkl::transpose::trans}\\ + A^\mathsf{H},& \text{oneapi::mkl::transpose::conjtrans} \end{cases} and :math:`\text{op}(A)` is an ``m``-by-``k`` matrix , :math:`\text{op}(B)` is diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst index ed3768f5a..db4bcf615 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst @@ -25,8 +25,8 @@ matrix modifier for :math:`A` using the following description: .. math:: \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} + A^\mathsf{T},& \text{oneapi::mkl::transpose::trans}\\ + A^\mathsf{H},& \text{oneapi::mkl::transpose::conjtrans} \end{cases} and :math:`\text{op}(A)` is an ``m``-by-``n`` matrix , :math:`x` is a vector of diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst index 8a178de28..fe9466b48 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst @@ -25,8 +25,8 @@ following description: .. math:: \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} + A^\mathsf{T},& \text{oneapi::mkl::transpose::trans}\\ + A^\mathsf{H},& \text{oneapi::mkl::transpose::conjtrans} \end{cases} and :math:`\text{op}(A)` is an ``m``-by-``m`` matrix , :math:`x` and :math:`y` From 2b00cf571c6c0a0886d2af38e078870cc32d6d2c Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Mon, 11 Mar 2024 16:32:16 +0000 Subject: [PATCH 12/52] Reword and format spsv description --- .../oneMKL/source/domains/spblas/operations/spsv.rst | 9 +++++---- source/elements/oneMKL/source/domains/spblas/spblas.rst | 2 +- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst index fe9466b48..08a51fcbf 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst @@ -7,7 +7,8 @@ spsv ==== -Solves a system of linear equations for a triangular sparse matrix. +Solves a system of linear equations where the coefficients are described by a +triangular sparse matrix. .. rubric:: Description and Assumptions @@ -18,9 +19,9 @@ for a square matrix: \text{op}(A) \cdot y \leftarrow \alpha \cdot x -where :math:`\alpha` is a scalar, :math:`A` is a triangular sparse matrix, :math:`x` and :math:`y` are -dense vectors, :math:`\text{op}()` is a matrix modifier for :math:`A` using the -following description: +where :math:`\alpha` is a scalar, :math:`A` is a triangular sparse matrix, +:math:`x` and :math:`y` are dense vectors, :math:`\text{op}()` is a matrix +modifier for :math:`A` using the following description: .. math:: diff --git a/source/elements/oneMKL/source/domains/spblas/spblas.rst b/source/elements/oneMKL/source/domains/spblas/spblas.rst index 34fc6c6ca..30e2cd3d3 100644 --- a/source/elements/oneMKL/source/domains/spblas/spblas.rst +++ b/source/elements/oneMKL/source/domains/spblas/spblas.rst @@ -21,7 +21,7 @@ Sparse BLAS * - :ref:`onemkl_sparse_data_handles` - Matrix and vector handle types * - :ref:`onemkl_sparse_spsv_header` - - Solve a linear system with a triangular sparse matrix + - Solve a triangular sparse linear system * - :ref:`onemkl_sparse_spmv_header` - Compute the product of a sparse matrix with a dense vector * - :ref:`onemkl_sparse_spmm_header` From c863160c30fcef8b6c951e134a0146decc0d050e Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Mon, 11 Mar 2024 16:36:08 +0000 Subject: [PATCH 13/52] Reorder operations alphabetically --- .../elements/oneMKL/source/domains/spblas/spblas.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/spblas.rst b/source/elements/oneMKL/source/domains/spblas/spblas.rst index 30e2cd3d3..eef2b3fb4 100644 --- a/source/elements/oneMKL/source/domains/spblas/spblas.rst +++ b/source/elements/oneMKL/source/domains/spblas/spblas.rst @@ -20,20 +20,20 @@ Sparse BLAS - Description * - :ref:`onemkl_sparse_data_handles` - Matrix and vector handle types - * - :ref:`onemkl_sparse_spsv_header` - - Solve a triangular sparse linear system - * - :ref:`onemkl_sparse_spmv_header` - - Compute the product of a sparse matrix with a dense vector * - :ref:`onemkl_sparse_spmm_header` - Compute the product of a sparse matrix with a dense matrix + * - :ref:`onemkl_sparse_spmv_header` + - Compute the product of a sparse matrix with a dense vector + * - :ref:`onemkl_sparse_spsv_header` + - Solve a triangular sparse linear system .. toctree:: :hidden: data_types/data_handles - operations/spsv - operations/spmv operations/spmm + operations/spmv + operations/spsv matrix_view supported-types From 8a8f6759c7e3677668b1554f299d4f59b7328d9e Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Tue, 12 Mar 2024 10:11:22 +0000 Subject: [PATCH 14/52] Replace occurences of sparse_matrix_handle_t with matrix_handle_t --- .../domains/spblas/data_types/destroy_sparse_matrix.rst | 6 +++--- .../domains/spblas/data_types/set_matrix_property.rst | 8 ++++---- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/destroy_sparse_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/destroy_sparse_matrix.rst index d416d58ec..d319d5021 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/destroy_sparse_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/destroy_sparse_matrix.rst @@ -7,7 +7,7 @@ destroy_sparse_matrix ===================== -Destroys a ``sparse_matrix_handle_t`` object. +Destroys a ``matrix_handle_t`` object. .. rubric:: Description and Assumptions @@ -24,8 +24,8 @@ If a USM pointer was provided, the data is not free'd. namespace oneapi::mkl::sparse { - void destroy_sparse_matrix (sycl::queue &queue, - oneapi::mkl::sparse::sparse_matrix_handle_t smhandle); + void destroy_sparse_matrix (sycl::queue &queue, + oneapi::mkl::sparse::matrix_handle_t smhandle); } diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_property.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_property.rst index ee5893fe5..a39dfe6b4 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_property.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_property.rst @@ -39,7 +39,7 @@ Matrix properties set_matrix_property ------------------- -Set a property to a ``sparse_matrix_handle_t`` object. +Set a property to a ``matrix_handle_t`` object. .. rubric:: Description and Assumptions @@ -52,9 +52,9 @@ matrix handle. The property provides stronger guarantees than a :ref:`onemkl_spa namespace oneapi::mkl::sparse { - bool set_matrix_property (sycl::queue &queue, - oneapi::mkl::sparse::sparse_matrix_handle_t smhandle, - matrix_property property_value); + bool set_matrix_property (sycl::queue &queue, + oneapi::mkl::sparse::matrix_handle_t smhandle, + matrix_property property_value); } From 13825be51f602bbe1ca22f11a0844fe4d5ee2106 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Tue, 12 Mar 2024 14:12:46 +0000 Subject: [PATCH 15/52] Reword sparse_linear_algebra paragraph --- .../domains/sparse_linear_algebra.inc.rst | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/source/elements/oneMKL/source/domains/sparse_linear_algebra.inc.rst b/source/elements/oneMKL/source/domains/sparse_linear_algebra.inc.rst index 3dd6f871f..320be484d 100644 --- a/source/elements/oneMKL/source/domains/sparse_linear_algebra.inc.rst +++ b/source/elements/oneMKL/source/domains/sparse_linear_algebra.inc.rst @@ -9,18 +9,20 @@ Sparse Linear Algebra .. container:: - The oneAPI Math Kernel Library provides a Data Parallel C++ interface to some - of the Sparse Linear Algebra routines. + The oneAPI Math Kernel Library provides a C++ interface to some Sparse Linear + Algebra routines using SYCL. :ref:`onemkl_spblas` provides basic operations on sparse vectors and matrices, and separates them into three stages: query of the external workspace size, optimization stage and execution. For a given configuration, - the first two stages would typically be called once and the execution may be - called multiple times. During the optimization stage, the API inspects the - matrix properties including size, sparsity pattern and available parallelism, - and can apply matrix format or structure changes to enable a more optimized - algorithm. In the execution stage, multiple routine calls can take advantage - of the optimization stage data in order to improve performance. + the first two stages would typically be called once for a set of input + arguments and the execution stage may be called multiple times. During the + optimization stage, the API may inspect the matrix properties including size, + sparsity pattern and available parallelism, and may apply matrix format or + structure changes to enable a more optimized algorithm. User-provided matrix + data remain unmodified if such optimizations are made. In the execution + stage, multiple routine calls can take advantage of the optimization stage + data in order to improve performance. .. toctree:: :hidden: From c61ff7e65654ee7e0c9a59011b84b8f1f6bc7f26 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Tue, 12 Mar 2024 14:52:06 +0000 Subject: [PATCH 16/52] Avoid variable names in high level create_* functions description --- .../source/domains/spblas/data_types/create_coo_matrix.rst | 6 +++--- .../source/domains/spblas/data_types/create_csr_matrix.rst | 6 +++--- .../domains/spblas/data_types/create_dense_matrix.rst | 4 ++-- .../domains/spblas/data_types/create_dense_vector.rst | 4 ++-- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst index 42987282b..d7db81529 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst @@ -15,9 +15,9 @@ The ``oneapi::mkl::sparse::create_coo_matrix`` function initializes the ``matrix_handle_t`` object with the provided data. In the case of buffers, the reference count of the provided buffer is -incremented which extends the lifetime of the underlying buffer until the -``smhandle`` is destroyed with ``destroy_sparse_matrix`` or the data is reset with -``set_coo_matrix_data``. +incremented which extends the lifetime of the underlying buffer until the sparse +matrix handle is destroyed with ``destroy_sparse_matrix`` or the data is reset +with ``set_coo_matrix_data``. In the case of USM, the object does not take ownership of the data. diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst index cd186589a..23048f369 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst @@ -15,9 +15,9 @@ The ``oneapi::mkl::sparse::create_csr_matrix`` function initializes the ``matrix_handle_t`` object with the provided data. In the case of buffers, the reference count of the provided buffer is -incremented which extends the lifetime of the underlying buffer until the -``smhandle`` is destroyed with ``destroy_sparse_matrix`` or the data is reset with -``set_csr_matrix_data``. +incremented which extends the lifetime of the underlying buffer until the sparse +matrix handle is destroyed with ``destroy_sparse_matrix`` or the data is reset +with ``set_csr_matrix_data``. In the case of USM, the object does not take ownership of the data. diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_matrix.rst index 2f079a499..104fdf0b8 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_matrix.rst @@ -15,8 +15,8 @@ The ``oneapi::mkl::sparse::create_dense_matrix`` function initializes the ``dense_matrix_handle_t`` object with the provided data. In the case of buffers, the reference count of the provided buffer is -incremented which extends the lifetime of the underlying buffer until the -``dmhandle`` is destroyed with ``destroy_dense_matrix`` or the data is reset +incremented which extends the lifetime of the underlying buffer until the dense +matrix handle is destroyed with ``destroy_dense_matrix`` or the data is reset with ``set_dense_matrix_data``. In the case of USM, the object does not take ownership of the data. diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_vector.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_vector.rst index d71d8d007..7d4419967 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_vector.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_vector.rst @@ -15,8 +15,8 @@ The ``oneapi::mkl::sparse::create_dense_vector`` function initializes the ``dense_vector_handle_t`` object with the provided data. In the case of buffers, the reference count of the provided buffer is -incremented which extends the lifetime of the underlying buffer until the -``dvhandle`` is destroyed with ``destroy_dense_vector`` or the data is reset +incremented which extends the lifetime of the underlying buffer until the dense +vector handle is destroyed with ``destroy_dense_vector`` or the data is reset with ``set_dense_vector_data``. In the case of USM, the object does not take ownership of the data. From 13dd2e5721d52c730695e51fe3b5471580f0d75e Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Tue, 12 Mar 2024 16:17:50 +0000 Subject: [PATCH 17/52] Clarify that container sizes are minimum sizes --- .../spblas/data_types/create_coo_matrix.rst | 30 ++++++++--------- .../spblas/data_types/create_csr_matrix.rst | 32 +++++++++---------- .../spblas/data_types/create_dense_matrix.rst | 4 +-- .../spblas/data_types/create_dense_vector.rst | 6 ++-- .../spblas/data_types/set_coo_matrix_data.rst | 30 ++++++++--------- .../spblas/data_types/set_csr_matrix_data.rst | 32 +++++++++---------- .../data_types/set_dense_matrix_data.rst | 11 +++---- .../data_types/set_dense_vector_data.rst | 5 +-- 8 files changed, 75 insertions(+), 75 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst index d7db81529..a0c57595f 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst @@ -99,19 +99,19 @@ create_coo_matrix (Buffer version) in :ref:`onemkl_enum_index_base` enum class. row_ind - Buffer of length ``nnz`` containing the row indices in ``index``-based - numbering. Refer to :ref:`onemkl_sparse_coo` format for detailed - description of ``row_ind``. + Buffer of length at least ``nnz`` containing the row indices in + ``index``-based numbering. Refer to :ref:`onemkl_sparse_coo` format for + detailed description of ``row_ind``. col_ind - Buffer of length ``nnz`` containing the column indices in ``index``-based - numbering. Refer to :ref:`onemkl_sparse_coo` format for detailed - description of ``col_ind``. + Buffer of length at least ``nnz`` containing the column indices in + ``index``-based numbering. Refer to :ref:`onemkl_sparse_coo` format for + detailed description of ``col_ind``. val - Buffer of length ``nnz`` containing non-zero elements (and possibly - explicit zeros) of the input matrix. Refer to :ref:`onemkl_sparse_coo` - format for detailed description of ``val``. + Buffer of length at least ``nnz`` containing non-zero elements (and + possibly explicit zeros) of the input matrix. Refer to + :ref:`onemkl_sparse_coo` format for detailed description of ``val``. .. container:: section @@ -197,22 +197,22 @@ create_coo_matrix (USM version) in :ref:`onemkl_enum_index_base` enum class. row_ind - USM pointer of length ``nnz`` containing the row indices in + USM pointer of length at least ``nnz`` containing the row indices in ``index``-based numbering. Refer to :ref:`onemkl_sparse_coo` format for detailed description of ``row_ind``. The data must be accessible on the device. col_ind - USM pointer of length ``nnz`` containing the column indices in + USM pointer of length at least ``nnz`` containing the column indices in ``index``-based numbering. Refer to :ref:`onemkl_sparse_coo` format for detailed description of ``col_ind``. The data must be accessible on the device. val - USM pointer of length ``nnz`` containing non-zero elements (and possibly - explicit zeros) of the input matrix. Refer to :ref:`onemkl_sparse_coo` - format for detailed description of ``val``. The data must be accessible on - the device. + USM pointer of length at least ``nnz`` containing non-zero elements (and + possibly explicit zeros) of the input matrix. Refer to + :ref:`onemkl_sparse_coo` format for detailed description of ``val``. The + data must be accessible on the device. .. container:: section diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst index 23048f369..121314eb0 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst @@ -99,18 +99,18 @@ create_csr_matrix (Buffer version) in :ref:`onemkl_enum_index_base` enum class. row_ptr - Buffer of length ``num_rows+1``. Refer to :ref:`onemkl_sparse_csr` format - for detailed description of ``row_ptr``. + Buffer of length at least ``num_rows+1``. Refer to + :ref:`onemkl_sparse_csr` format for detailed description of ``row_ptr``. col_ind - Buffer of length ``nnz`` containing the column indices in ``index``-based - numbering. Refer to :ref:`onemkl_sparse_csr` format for detailed - description of ``col_ind``. + Buffer of length at least ``nnz`` containing the column indices in + ``index``-based numbering. Refer to :ref:`onemkl_sparse_csr` format for + detailed description of ``col_ind``. val - Buffer of length ``nnz`` containing non-zero elements (and possibly - explicit zeros) of the input matrix. Refer to :ref:`onemkl_sparse_csr` - format for detailed description of ``val``. + Buffer of length at least ``nnz`` containing non-zero elements (and + possibly explicit zeros) of the input matrix. Refer to + :ref:`onemkl_sparse_csr` format for detailed description of ``val``. .. container:: section @@ -196,21 +196,21 @@ create_csr_matrix (USM version) in :ref:`onemkl_enum_index_base` enum class. row_ptr - USM pointer of length ``num_rows+1``. Refer to :ref:`onemkl_sparse_csr` - format for detailed description of ``row_ptr``. The data must be - accessible on the device. + USM pointer of length at least ``num_rows+1``. Refer to + :ref:`onemkl_sparse_csr` format for detailed description of ``row_ptr``. + The data must be accessible on the device. col_ind - USM pointer of length ``nnz`` containing the column indices in + USM pointer of length at least ``nnz`` containing the column indices in ``index``-based numbering. Refer to :ref:`onemkl_sparse_csr` format for detailed description of ``col_ind``. The data must be accessible on the device. val - USM pointer of length ``nnz`` containing non-zero elements (and possibly - explicit zeros) of the input matrix. Refer to :ref:`onemkl_sparse_csr` - format for detailed description of ``val``. The data must be accessible on - the device. + USM pointer of length at least ``nnz`` containing non-zero elements (and + possibly explicit zeros) of the input matrix. Refer to + :ref:`onemkl_sparse_csr` format for detailed description of ``val``. The + data must be accessible on the device. .. container:: section diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_matrix.rst index 104fdf0b8..f2bf0132c 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_matrix.rst @@ -78,7 +78,7 @@ create_dense_matrix (Buffer version) Specify whether the data uses row major or column major. val - Buffer of length ``ld*num_cols`` if column major is used or + Buffer of length at least ``ld*num_cols`` if column major is used or ``ld*num_rows`` if row major is used. Holds the data to initialize ``p_dmhandle`` with. @@ -161,7 +161,7 @@ create_dense_matrix (USM version) Specify whether the data uses row major or column major. val - USM pointer of length ``ld*num_cols`` if column major is used or + USM pointer of length at least ``ld*num_cols`` if column major is used or ``ld*num_rows`` if row major is used. Holds the data to initialize ``p_dmhandle`` with. The data must be accessible on the device. diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_vector.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_vector.rst index 7d4419967..74049033e 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_vector.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_vector.rst @@ -64,8 +64,8 @@ create_dense_vector (Buffer version) Number of elements of the provided data ``val``. Must be at least 0. val - Buffer of length ``size``. Holds the data to initialize ``p_dvhandle`` - with. + Buffer of length at least ``size``. Holds the data to initialize + ``p_dvhandle`` with. .. container:: section @@ -132,7 +132,7 @@ create_dense_vector (USM version) Number of elements of the provided data ``val``. Must be at least 0. val - USM pointer of length ``size``. Holds the data to initialize + USM pointer of length at least ``size``. Holds the data to initialize ``p_dvhandle`` with. The data must be accessible on the device. .. container:: section diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst index 348c4a829..859197d4f 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst @@ -84,19 +84,19 @@ set_coo_matrix_data (Buffer version) in :ref:`onemkl_enum_index_base` enum class. row_ind - Buffer of length ``nnz`` containing the row indices in ``index``-based - numbering. Refer to :ref:`onemkl_sparse_coo` format for detailed - description of ``row_ind``. + Buffer of length at least ``nnz`` containing the row indices in + ``index``-based numbering. Refer to :ref:`onemkl_sparse_coo` format for + detailed description of ``row_ind``. col_ind - Buffer of length ``nnz`` containing the column indices in ``index``-based - numbering. Refer to :ref:`onemkl_sparse_coo` format for detailed - description of ``col_ind``. + Buffer of length at least ``nnz`` containing the column indices in + ``index``-based numbering. Refer to :ref:`onemkl_sparse_coo` format for + detailed description of ``col_ind``. val - Buffer of length ``nnz`` containing non-zero elements (and possibly - explicit zeros) of the input matrix. Refer to :ref:`onemkl_sparse_coo` - format for detailed description of ``val``. + Buffer of length at least ``nnz`` containing non-zero elements (and + possibly explicit zeros) of the input matrix. Refer to + :ref:`onemkl_sparse_coo` format for detailed description of ``val``. .. container:: section @@ -174,22 +174,22 @@ set_coo_matrix_data (USM version) in :ref:`onemkl_enum_index_base` enum class. row_ind - USM pointer of length ``nnz`` containing the row indices in + USM pointer of length at least ``nnz`` containing the row indices in ``index``-based numbering. Refer to :ref:`onemkl_sparse_coo` format for detailed description of ``row_ind``. The data must be accessible on the device. col_ind - USM pointer of length ``nnz`` containing the column indices in + USM pointer of length at least ``nnz`` containing the column indices in ``index``-based numbering. Refer to :ref:`onemkl_sparse_coo` format for detailed description of ``col_ind``. The data must be accessible on the device. val - USM pointer of length ``nnz`` containing non-zero elements (and possibly - explicit zeros) of the input matrix. Refer to :ref:`onemkl_sparse_coo` - format for detailed description of ``val``. The data must be accessible on - the device. + USM pointer of length at least ``nnz`` containing non-zero elements (and + possibly explicit zeros) of the input matrix. Refer to + :ref:`onemkl_sparse_coo` format for detailed description of ``val``. The + data must be accessible on the device. .. container:: section diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst index bbd461c2f..2394a15be 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst @@ -84,18 +84,18 @@ set_csr_matrix_data (Buffer version) in :ref:`onemkl_enum_index_base` enum class. row_ptr - Buffer of length ``num_rows+1``. Refer to :ref:`onemkl_sparse_csr` format - for detailed description of ``row_ptr``. + Buffer of length at least ``num_rows+1``. Refer to + :ref:`onemkl_sparse_csr` format for detailed description of ``row_ptr``. col_ind - Buffer of length ``nnz`` containing the column indices in ``index``-based - numbering. Refer to :ref:`onemkl_sparse_csr` format for detailed - description of ``col_ind``. + Buffer of length at least ``nnz`` containing the column indices in + ``index``-based numbering. Refer to :ref:`onemkl_sparse_csr` format for + detailed description of ``col_ind``. val - Buffer of length ``nnz`` containing non-zero elements (and possibly - explicit zeros) of the input matrix. Refer to :ref:`onemkl_sparse_csr` - format for detailed description of ``val``. + Buffer of length at least ``nnz`` containing non-zero elements (and + possibly explicit zeros) of the input matrix. Refer to + :ref:`onemkl_sparse_csr` format for detailed description of ``val``. .. container:: section @@ -173,21 +173,21 @@ set_csr_matrix_data (USM version) in :ref:`onemkl_enum_index_base` enum class. row_ptr - USM pointer of length ``num_rows+1``. Refer to :ref:`onemkl_sparse_csr` - format for detailed description of ``row_ptr``. The data must be - accessible on the device. + USM pointer of length at least ``num_rows+1``. Refer to + :ref:`onemkl_sparse_csr` format for detailed description of ``row_ptr``. + The data must be accessible on the device. col_ind - USM pointer of length ``nnz`` containing the column indices in + USM pointer of length at least ``nnz`` containing the column indices in ``index``-based numbering. Refer to :ref:`onemkl_sparse_csr` format for detailed description of ``col_ind``. The data must be accessible on the device. val - USM pointer of length ``nnz`` containing non-zero elements (and possibly - explicit zeros) of the input matrix. Refer to :ref:`onemkl_sparse_csr` - format for detailed description of ``val``. The data must be accessible on - the device. + USM pointer of length at least ``nnz`` containing non-zero elements (and + possibly explicit zeros) of the input matrix. Refer to + :ref:`onemkl_sparse_csr` format for detailed description of ``val``. The + data must be accessible on the device. .. container:: section diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst index 705359c71..789952e02 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst @@ -79,9 +79,8 @@ set_dense_matrix_data (Buffer version) Specify whether the data uses row major or column major. val - Buffer of length ``ld*num_cols`` if column major is used or - ``ld*num_rows`` if row major is used. Holds the data to initialize - ``dmhandle`` with. + Buffer of length at least ``ld*num_cols`` if column major is used or + ``ld*num_rows`` if row major is used. .. container:: section @@ -154,9 +153,9 @@ set_dense_matrix_data (USM version) Specify whether the data uses row major or column major. val - USM pointer of length ``ld*num_cols`` if column major is used or - ``ld*num_rows`` if row major is used. Holds the data to initialize - ``dmhandle`` with. The data must be accessible on the device. + USM pointer of length at least ``ld*num_cols`` if column major is used or + ``ld*num_rows`` if row major is used. The data must be accessible on the + device. .. container:: section diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst index 6a1c1db75..1020c5015 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst @@ -65,7 +65,7 @@ set_dense_vector_data (Buffer version) Number of elements of the provided data ``val``. Must be at least 0. val - Buffer of length ``size``. + Buffer of length at least ``size``. .. container:: section @@ -124,7 +124,8 @@ set_dense_vector_data (USM version) Number of elements of the provided data ``val``. Must be at least 0. val - USM pointer of length ``size``. The data must be accessible on the device. + USM pointer of length at least ``size``. The data must be accessible on + the device. .. container:: section From ad83d1c3e00c16af41cf7adbacf02ab44fd8e3e0 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Wed, 13 Mar 2024 15:47:42 +0000 Subject: [PATCH 18/52] Clarify requirements on the COO and CSR sizes --- .../spblas/data_types/create_coo_matrix.rst | 16 ++++++++++++++++ .../spblas/data_types/create_csr_matrix.rst | 16 ++++++++++++++++ .../spblas/data_types/create_dense_matrix.rst | 8 ++++---- .../spblas/data_types/create_dense_vector.rst | 4 ++-- .../spblas/data_types/set_coo_matrix_data.rst | 16 ++++++++++++++++ .../spblas/data_types/set_csr_matrix_data.rst | 16 ++++++++++++++++ .../spblas/data_types/set_dense_matrix_data.rst | 4 ++-- .../spblas/data_types/set_dense_vector_data.rst | 2 +- 8 files changed, 73 insertions(+), 9 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst index a0c57595f..80dfb128b 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst @@ -122,6 +122,14 @@ create_coo_matrix (Buffer version) initialized ``matrix_handle_t`` object that can be filled and used to perform sparse BLAS operations. +.. container:: section + + .. rubric:: Notes + + - The parameters ``num_rows``, ``num_cols`` and ``nnz`` may be zero if and + only if ``row_ind``, ``col_ind`` and ``val`` are zero-sized, otherwise they + must be strictly greater than zero. + .. container:: section .. rubric:: Throws @@ -223,6 +231,14 @@ create_coo_matrix (USM version) initialized ``matrix_handle_t`` object that can be filled and used to perform sparse BLAS operations. +.. container:: section + + .. rubric:: Notes + + - The parameters ``num_rows``, ``num_cols`` and ``nnz`` may be zero if and + only if ``row_ind``, ``col_ind`` and ``val`` are null pointers, otherwise + they must be strictly greater than zero. + .. container:: section .. rubric:: Throws diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst index 121314eb0..8a530437a 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst @@ -121,6 +121,14 @@ create_csr_matrix (Buffer version) initialized ``matrix_handle_t`` object that can be filled and used to perform sparse BLAS operations. +.. container:: section + + .. rubric:: Notes + + - The parameters ``num_rows``, ``num_cols`` and ``nnz`` may be zero if and + only if ``row_ptr``, ``col_ind`` and ``val`` are zero-sized, otherwise they + must be strictly greater than zero. + .. container:: section .. rubric:: Throws @@ -221,6 +229,14 @@ create_csr_matrix (USM version) initialized ``matrix_handle_t`` object that can be filled and used to perform sparse BLAS operations. +.. container:: section + + .. rubric:: Notes + + - The parameters ``num_rows``, ``num_cols`` and ``nnz`` may be zero if and + only if ``row_ptr``, ``col_ind`` and ``val`` are null pointers, otherwise + they must be strictly greater than zero. + .. container:: section .. rubric:: Throws diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_matrix.rst index f2bf0132c..d3961be16 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_matrix.rst @@ -64,10 +64,10 @@ create_dense_matrix (Buffer version) called on an uninitialized ``dense_matrix_handle_t`` object. num_rows - Number of rows of the provided data ``val``. Must be at least 0. + Number of rows of the provided data ``val``. Must be at least 1. num_cols - Number of columns of the provided data ``val``. Must be at least 0. + Number of columns of the provided data ``val``. Must be at least 1. ld Leading dimension of the provided data ``val``. Must be at least @@ -147,10 +147,10 @@ create_dense_matrix (USM version) called on an uninitialized ``dense_matrix_handle_t`` object. num_rows - Number of rows of the provided data ``val``. Must be at least 0. + Number of rows of the provided data ``val``. Must be at least 1. num_cols - Number of columns of the provided data ``val``. Must be at least 0. + Number of columns of the provided data ``val``. Must be at least 1. ld Leading dimension of the provided data ``val``. Must be at least diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_vector.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_vector.rst index 74049033e..795234cfd 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_vector.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_vector.rst @@ -61,7 +61,7 @@ create_dense_vector (Buffer version) called on an uninitialized ``dense_vector_handle_t`` object. size - Number of elements of the provided data ``val``. Must be at least 0. + Number of elements of the provided data ``val``. Must be at least 1. val Buffer of length at least ``size``. Holds the data to initialize @@ -129,7 +129,7 @@ create_dense_vector (USM version) called on an uninitialized ``dense_vector_handle_t`` object. size - Number of elements of the provided data ``val``. Must be at least 0. + Number of elements of the provided data ``val``. Must be at least 1. val USM pointer of length at least ``size``. Holds the data to initialize diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst index 859197d4f..7b8d8d6f8 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst @@ -98,6 +98,14 @@ set_coo_matrix_data (Buffer version) possibly explicit zeros) of the input matrix. Refer to :ref:`onemkl_sparse_coo` format for detailed description of ``val``. +.. container:: section + + .. rubric:: Notes + + - The parameters ``num_rows``, ``num_cols`` and ``nnz`` may be zero if and + only if ``row_ind``, ``col_ind`` and ``val`` are zero-sized, otherwise they + must be strictly greater than zero. + .. container:: section .. rubric:: Throws @@ -191,6 +199,14 @@ set_coo_matrix_data (USM version) :ref:`onemkl_sparse_coo` format for detailed description of ``val``. The data must be accessible on the device. +.. container:: section + + .. rubric:: Notes + + - The parameters ``num_rows``, ``num_cols`` and ``nnz`` may be zero if and + only if ``row_ind``, ``col_ind`` and ``val`` are null pointers, otherwise + they must be strictly greater than zero. + .. container:: section .. rubric:: Throws diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst index 2394a15be..6c76bf877 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst @@ -97,6 +97,14 @@ set_csr_matrix_data (Buffer version) possibly explicit zeros) of the input matrix. Refer to :ref:`onemkl_sparse_csr` format for detailed description of ``val``. +.. container:: section + + .. rubric:: Notes + + - The parameters ``num_rows``, ``num_cols`` and ``nnz`` may be zero if and + only if ``row_ptr``, ``col_ind`` and ``val`` are zero-sized, otherwise they + must be strictly greater than zero. + .. container:: section .. rubric:: Throws @@ -189,6 +197,14 @@ set_csr_matrix_data (USM version) :ref:`onemkl_sparse_csr` format for detailed description of ``val``. The data must be accessible on the device. +.. container:: section + + .. rubric:: Notes + + - The parameters ``num_rows``, ``num_cols`` and ``nnz`` may be zero if and + only if ``row_ptr``, ``col_ind`` and ``val`` are null pointers, otherwise + they must be strictly greater than zero. + .. container:: section .. rubric:: Throws diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst index 789952e02..8a917c213 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst @@ -139,10 +139,10 @@ set_dense_matrix_data (USM version) Handle already initialized with :ref:`onemkl_sparse_create_dense_matrix`. num_rows - Number of rows of the provided data ``val``. Must be at least 0. + Number of rows of the provided data ``val``. Must be at least 1. num_cols - Number of columns of the provided data ``val``. Must be at least 0. + Number of columns of the provided data ``val``. Must be at least 1. ld Leading dimension of the provided data ``val``. Must be at least diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst index 1020c5015..d07f0518e 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst @@ -121,7 +121,7 @@ set_dense_vector_data (USM version) Handle already initialized with :ref:`onemkl_sparse_create_dense_vector`. size - Number of elements of the provided data ``val``. Must be at least 0. + Number of elements of the provided data ``val``. Must be at least 1. val USM pointer of length at least ``size``. The data must be accessible on From b7037b5dd74b9055e69f2682ae55a2b01311a001 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Wed, 13 Mar 2024 15:49:42 +0000 Subject: [PATCH 19/52] Document that using smaller USM pointer is undefined behavior --- .../source/domains/spblas/data_types/create_coo_matrix.rst | 3 ++- .../source/domains/spblas/data_types/create_csr_matrix.rst | 3 ++- .../source/domains/spblas/data_types/create_dense_matrix.rst | 3 ++- .../source/domains/spblas/data_types/create_dense_vector.rst | 3 ++- .../source/domains/spblas/data_types/set_coo_matrix_data.rst | 3 ++- .../source/domains/spblas/data_types/set_csr_matrix_data.rst | 3 ++- .../source/domains/spblas/data_types/set_dense_matrix_data.rst | 3 ++- .../source/domains/spblas/data_types/set_dense_vector_data.rst | 3 ++- 8 files changed, 16 insertions(+), 8 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst index 80dfb128b..d3d431daf 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst @@ -220,7 +220,8 @@ create_coo_matrix (USM version) USM pointer of length at least ``nnz`` containing non-zero elements (and possibly explicit zeros) of the input matrix. Refer to :ref:`onemkl_sparse_coo` format for detailed description of ``val``. The - data must be accessible on the device. + data must be accessible on the device. Using a USM pointer with a smaller + allocated memory size is undefined behavior. .. container:: section diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst index 8a530437a..bdc0e8328 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst @@ -218,7 +218,8 @@ create_csr_matrix (USM version) USM pointer of length at least ``nnz`` containing non-zero elements (and possibly explicit zeros) of the input matrix. Refer to :ref:`onemkl_sparse_csr` format for detailed description of ``val``. The - data must be accessible on the device. + data must be accessible on the device. Using a USM pointer with a smaller + allocated memory size is undefined behavior. .. container:: section diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_matrix.rst index d3961be16..4e65176b9 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_matrix.rst @@ -163,7 +163,8 @@ create_dense_matrix (USM version) val USM pointer of length at least ``ld*num_cols`` if column major is used or ``ld*num_rows`` if row major is used. Holds the data to initialize - ``p_dmhandle`` with. The data must be accessible on the device. + ``p_dmhandle`` with. The data must be accessible on the device. Using a + USM pointer with a smaller allocated memory size is undefined behavior. .. container:: section diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_vector.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_vector.rst index 795234cfd..e99322f62 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_vector.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_vector.rst @@ -133,7 +133,8 @@ create_dense_vector (USM version) val USM pointer of length at least ``size``. Holds the data to initialize - ``p_dvhandle`` with. The data must be accessible on the device. + ``p_dvhandle`` with. The data must be accessible on the device. Using a + USM pointer with a smaller allocated memory size is undefined behavior. .. container:: section diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst index 7b8d8d6f8..f5528c701 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst @@ -197,7 +197,8 @@ set_coo_matrix_data (USM version) USM pointer of length at least ``nnz`` containing non-zero elements (and possibly explicit zeros) of the input matrix. Refer to :ref:`onemkl_sparse_coo` format for detailed description of ``val``. The - data must be accessible on the device. + data must be accessible on the device. Using a USM pointer with a smaller + allocated memory size is undefined behavior. .. container:: section diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst index 6c76bf877..e3edef330 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst @@ -195,7 +195,8 @@ set_csr_matrix_data (USM version) USM pointer of length at least ``nnz`` containing non-zero elements (and possibly explicit zeros) of the input matrix. Refer to :ref:`onemkl_sparse_csr` format for detailed description of ``val``. The - data must be accessible on the device. + data must be accessible on the device. Using a USM pointer with a smaller + allocated memory size is undefined behavior. .. container:: section diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst index 8a917c213..490190809 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst @@ -155,7 +155,8 @@ set_dense_matrix_data (USM version) val USM pointer of length at least ``ld*num_cols`` if column major is used or ``ld*num_rows`` if row major is used. The data must be accessible on the - device. + device. Using a USM pointer with a smaller allocated memory size is + undefined behavior. .. container:: section diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst index d07f0518e..b8f83beed 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst @@ -125,7 +125,8 @@ set_dense_vector_data (USM version) val USM pointer of length at least ``size``. The data must be accessible on - the device. + the device. Using a USM pointer with a smaller allocated memory size is + undefined behavior. .. container:: section From 4db05aa0dc4b077fc6005f84682de590810718f5 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Wed, 13 Mar 2024 15:52:08 +0000 Subject: [PATCH 20/52] Remove onemkl_exception_device_bad_alloc from create_* and set_*_data functions --- .../source/domains/spblas/data_types/create_coo_matrix.rst | 2 -- .../source/domains/spblas/data_types/create_csr_matrix.rst | 2 -- .../source/domains/spblas/data_types/create_dense_matrix.rst | 2 -- .../source/domains/spblas/data_types/create_dense_vector.rst | 2 -- .../source/domains/spblas/data_types/set_coo_matrix_data.rst | 2 -- .../source/domains/spblas/data_types/set_csr_matrix_data.rst | 2 -- .../source/domains/spblas/data_types/set_dense_matrix_data.rst | 2 -- .../source/domains/spblas/data_types/set_dense_vector_data.rst | 2 -- 8 files changed, 16 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst index d3d431daf..c5aceb040 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst @@ -139,7 +139,6 @@ create_coo_matrix (Buffer version) implementation-specific exception(s) in case of error conditions not covered here. - | :ref:`oneapi::mkl::device_bad_alloc` | :ref:`oneapi::mkl::host_bad_alloc` | :ref:`oneapi::mkl::invalid_argument` | :ref:`oneapi::mkl::unimplemented` @@ -249,7 +248,6 @@ create_coo_matrix (USM version) implementation-specific exception(s) in case of error conditions not covered here. - | :ref:`oneapi::mkl::device_bad_alloc` | :ref:`oneapi::mkl::host_bad_alloc` | :ref:`oneapi::mkl::invalid_argument` | :ref:`oneapi::mkl::unimplemented` diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst index bdc0e8328..59c297f89 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst @@ -138,7 +138,6 @@ create_csr_matrix (Buffer version) implementation-specific exception(s) in case of error conditions not covered here. - | :ref:`oneapi::mkl::device_bad_alloc` | :ref:`oneapi::mkl::host_bad_alloc` | :ref:`oneapi::mkl::invalid_argument` | :ref:`oneapi::mkl::unimplemented` @@ -247,7 +246,6 @@ create_csr_matrix (USM version) implementation-specific exception(s) in case of error conditions not covered here. - | :ref:`oneapi::mkl::device_bad_alloc` | :ref:`oneapi::mkl::host_bad_alloc` | :ref:`oneapi::mkl::invalid_argument` | :ref:`oneapi::mkl::unimplemented` diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_matrix.rst index 4e65176b9..60d4cb598 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_matrix.rst @@ -100,7 +100,6 @@ create_dense_matrix (Buffer version) implementation-specific exception(s) in case of error conditions not covered here. - | :ref:`oneapi::mkl::device_bad_alloc` | :ref:`oneapi::mkl::host_bad_alloc` | :ref:`oneapi::mkl::invalid_argument` | :ref:`oneapi::mkl::unimplemented` @@ -184,7 +183,6 @@ create_dense_matrix (USM version) implementation-specific exception(s) in case of error conditions not covered here. - | :ref:`oneapi::mkl::device_bad_alloc` | :ref:`oneapi::mkl::host_bad_alloc` | :ref:`oneapi::mkl::invalid_argument` | :ref:`oneapi::mkl::unimplemented` diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_vector.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_vector.rst index e99322f62..f282ecd7e 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_vector.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_vector.rst @@ -85,7 +85,6 @@ create_dense_vector (Buffer version) implementation-specific exception(s) in case of error conditions not covered here. - | :ref:`oneapi::mkl::device_bad_alloc` | :ref:`oneapi::mkl::host_bad_alloc` | :ref:`oneapi::mkl::invalid_argument` | :ref:`oneapi::mkl::unimplemented` @@ -154,7 +153,6 @@ create_dense_vector (USM version) implementation-specific exception(s) in case of error conditions not covered here. - | :ref:`oneapi::mkl::device_bad_alloc` | :ref:`oneapi::mkl::host_bad_alloc` | :ref:`oneapi::mkl::invalid_argument` | :ref:`oneapi::mkl::unimplemented` diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst index f5528c701..1b8e1f732 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst @@ -115,7 +115,6 @@ set_coo_matrix_data (Buffer version) implementation-specific exception(s) in case of error conditions not covered here. - | :ref:`oneapi::mkl::device_bad_alloc` | :ref:`oneapi::mkl::invalid_argument` | :ref:`oneapi::mkl::unimplemented` | :ref:`oneapi::mkl::uninitialized` @@ -217,7 +216,6 @@ set_coo_matrix_data (USM version) implementation-specific exception(s) in case of error conditions not covered here. - | :ref:`oneapi::mkl::device_bad_alloc` | :ref:`oneapi::mkl::invalid_argument` | :ref:`oneapi::mkl::unimplemented` | :ref:`oneapi::mkl::uninitialized` diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst index e3edef330..547629e33 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst @@ -114,7 +114,6 @@ set_csr_matrix_data (Buffer version) implementation-specific exception(s) in case of error conditions not covered here. - | :ref:`oneapi::mkl::device_bad_alloc` | :ref:`oneapi::mkl::invalid_argument` | :ref:`oneapi::mkl::unimplemented` | :ref:`oneapi::mkl::uninitialized` @@ -215,7 +214,6 @@ set_csr_matrix_data (USM version) implementation-specific exception(s) in case of error conditions not covered here. - | :ref:`oneapi::mkl::device_bad_alloc` | :ref:`oneapi::mkl::invalid_argument` | :ref:`oneapi::mkl::unimplemented` | :ref:`oneapi::mkl::uninitialized` diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst index 490190809..a4beb7ef3 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst @@ -91,7 +91,6 @@ set_dense_matrix_data (Buffer version) implementation-specific exception(s) in case of error conditions not covered here. - | :ref:`oneapi::mkl::device_bad_alloc` | :ref:`oneapi::mkl::invalid_argument` | :ref:`oneapi::mkl::unimplemented` | :ref:`oneapi::mkl::uninitialized` @@ -167,7 +166,6 @@ set_dense_matrix_data (USM version) implementation-specific exception(s) in case of error conditions not covered here. - | :ref:`oneapi::mkl::device_bad_alloc` | :ref:`oneapi::mkl::invalid_argument` | :ref:`oneapi::mkl::unimplemented` | :ref:`oneapi::mkl::uninitialized` diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst index b8f83beed..dcdbf1b76 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst @@ -76,7 +76,6 @@ set_dense_vector_data (Buffer version) implementation-specific exception(s) in case of error conditions not covered here. - | :ref:`oneapi::mkl::device_bad_alloc` | :ref:`oneapi::mkl::invalid_argument` | :ref:`oneapi::mkl::unimplemented` | :ref:`oneapi::mkl::uninitialized` @@ -137,7 +136,6 @@ set_dense_vector_data (USM version) implementation-specific exception(s) in case of error conditions not covered here. - | :ref:`oneapi::mkl::device_bad_alloc` | :ref:`oneapi::mkl::invalid_argument` | :ref:`oneapi::mkl::unimplemented` | :ref:`oneapi::mkl::uninitialized` From 90c4cec984f71f62b1f60d19080cabd3ae643408 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Thu, 14 Mar 2024 16:51:03 +0000 Subject: [PATCH 21/52] Fix matrix_view todo --- .../elements/oneMKL/source/domains/spblas/matrix_view.rst | 8 ++------ .../oneMKL/source/domains/spblas/operations/spsv.rst | 3 ++- 2 files changed, 4 insertions(+), 7 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/matrix_view.rst b/source/elements/oneMKL/source/domains/spblas/matrix_view.rst index 81187093a..000ba1e78 100644 --- a/source/elements/oneMKL/source/domains/spblas/matrix_view.rst +++ b/source/elements/oneMKL/source/domains/spblas/matrix_view.rst @@ -32,11 +32,7 @@ matrix_descr .. rubric:: Description - The matrix descriptor is an optional property that can optimize some - operations. - - TODO: Clarify are triangular operations going to require a triangular - matrix_descr or should it be ignored? + The matrix descriptor describes how an operation should interpret the data. .. list-table:: :header-rows: 1 @@ -91,7 +87,7 @@ matrix_view The ``uplo_view`` member is only used if ``type_view`` is ``symmetric``, ``hermitian`` or ``triangular``. - The ``diag_view`` member is only used if ``type_view`` is ``diagonal``. + The ``diag_view`` member is ignored if ``type_view`` is ``general``. .. rubric:: Syntax diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst index 08a51fcbf..c556beb29 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst @@ -266,7 +266,8 @@ spsv A_view Specifies which part of the handle should be read as described by - :ref:`onemkl_sparse_matrix_view`. + :ref:`onemkl_sparse_matrix_view`. ``A_view.type_view`` must be + ``matrix_descr::triangular`` or ``matrix_descr::diagonal``. A_handle Sparse matrix handle object representing :math:`A`. From 094292667371ff600d778e87f9d0f69055ba0268 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Thu, 14 Mar 2024 17:20:59 +0000 Subject: [PATCH 22/52] Fix diagonal property description --- .../domains/spblas/data_types/set_matrix_property.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_property.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_property.rst index a39dfe6b4..d5b0f6177 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_property.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_property.rst @@ -29,9 +29,9 @@ Matrix properties * - Value - Description * - ``symmetric`` - - Guarantees that the matrix is symmetric, meaning it must be square and - its transpose is equal to itself. TODO: Confirm whether the user can - only provide half of the data in this case? + - Guarantees that the user-provided matrix data are symmetric, meaning + the matrix is square, the user data contain both lower and upper + triangular regions, and that its transpose is equal to itself. * - ``sorted`` - Guarantees that the column indices are sorted for a given row. Only available for the CSR format. TODO: Confirm the description. From dd541fe3c69a52bec136cdb9aaa933289047b80d Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Thu, 14 Mar 2024 18:20:51 +0000 Subject: [PATCH 23/52] Use bitmask for matrix properties --- .../spblas/data_types/data_handles.rst | 4 +- ...property.rst => set_matrix_properties.rst} | 48 +++++++++++-------- .../source/domains/spblas/operations/spmm.rst | 2 + .../source/domains/spblas/operations/spmv.rst | 2 + .../source/domains/spblas/operations/spsv.rst | 2 + 5 files changed, 36 insertions(+), 22 deletions(-) rename source/elements/oneMKL/source/domains/spblas/data_types/{set_matrix_property.rst => set_matrix_properties.rst} (57%) diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/data_handles.rst b/source/elements/oneMKL/source/domains/spblas/data_types/data_handles.rst index 57c235116..db348e234 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/data_handles.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/data_handles.rst @@ -97,7 +97,7 @@ Sparse matrix handle - :ref:`onemkl_sparse_create_csr_matrix` - :ref:`onemkl_sparse_set_coo_matrix_data` - :ref:`onemkl_sparse_set_csr_matrix_data` - - :ref:`onemkl_sparse_set_matrix_property` + - :ref:`onemkl_sparse_set_matrix_properties` - :ref:`onemkl_sparse_destroy_sparse_matrix` See a description of the supported :ref:`sparse formats`. @@ -116,7 +116,7 @@ Sparse matrix handle destroy_dense_vector destroy_dense_matrix destroy_sparse_matrix - set_matrix_property + set_matrix_properties format-descriptions **Parent topic:** :ref:`onemkl_spblas` diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_property.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_properties.rst similarity index 57% rename from source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_property.rst rename to source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_properties.rst index d5b0f6177..db6b502a1 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_property.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_properties.rst @@ -2,10 +2,10 @@ .. .. SPDX-License-Identifier: CC-BY-4.0 -.. _onemkl_sparse_set_matrix_property: +.. _onemkl_sparse_set_matrix_properties: -set_matrix_property -=================== +set_matrix_properties +===================== Matrix properties ----------------- @@ -14,13 +14,19 @@ Matrix properties .. code:: cpp - enum class matrix_property { - symmetric, - sorted, - }; + namespace oneapi::mkl::sparse { - TODO: Clarify are the properties meant to be used as a bit mask so multiple - properties can be set? + enum matrix_property : std::int32_t { + symmetric = 1 << 0, + sorted = 1 << 1, + }; + + } + + Matrix properties are optional and "strong" guarantees. Unlike + :ref:`onemkl_sparse_matrix_view`, the user must ensure that the handle's data + holds all the given properties. A property can be set to optimize some + operations. .. list-table:: :header-rows: 1 @@ -36,15 +42,15 @@ Matrix properties - Guarantees that the column indices are sorted for a given row. Only available for the CSR format. TODO: Confirm the description. -set_matrix_property -------------------- +set_matrix_properties +--------------------- -Set a property to a ``matrix_handle_t`` object. +Set properties to a ``matrix_handle_t`` object. .. rubric:: Description and Assumptions -The ``oneapi::mkl::sparse::set_matrix_property`` function sets a property to a -matrix handle. The property provides stronger guarantees than a :ref:`onemkl_sparse_matrix_view`. +The ``oneapi::mkl::sparse::set_matrix_properties`` function sets properties to a +matrix handle. .. rubric:: Syntax @@ -52,9 +58,9 @@ matrix handle. The property provides stronger guarantees than a :ref:`onemkl_spa namespace oneapi::mkl::sparse { - bool set_matrix_property (sycl::queue &queue, - oneapi::mkl::sparse::matrix_handle_t smhandle, - matrix_property property_value); + bool set_matrix_properties (sycl::queue &queue, + oneapi::mkl::sparse::matrix_handle_t smhandle, + std::int32_t properties_mask); } @@ -68,14 +74,16 @@ matrix handle. The property provides stronger guarantees than a :ref:`onemkl_spa smhandle Initialized sparse matrix handle. - property_value - Matrix property to set. + properties_mask + Matrix properties to set. The mask must be composed of one or multiple + values from ``oneapi::mkl::sparse::matrix_property`` combined with the + bitwise-or operator ``|``. Properties can be reset with a mask of 0. .. container:: section .. rubric:: Return Values - Return whether the property was set to the backend's handle. A backend may + Return whether the properties were set to the backend's handle. A backend may not have equivalent properties. .. container:: section diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst index f9fbcf0ed..1a44c0f84 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst @@ -42,8 +42,10 @@ spmm_descr .. code-block:: cpp namespace oneapi::mkl::sparse { + struct spmm_descr; using spmm_descr_t = spmm_descr*; + } .. container:: section diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst index db4bcf615..336db2c66 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst @@ -42,8 +42,10 @@ spmv_descr .. code-block:: cpp namespace oneapi::mkl::sparse { + struct spmv_descr; using spmv_descr_t = spmv_descr*; + } .. container:: section diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst index c556beb29..4f19ba17f 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst @@ -43,8 +43,10 @@ spsv_descr .. code-block:: cpp namespace oneapi::mkl::sparse { + struct spsv_descr; using spsv_descr_t = spsv_descr*; + } .. container:: section From 4b66461cc71418bedd4c0f0dc6a99b596b27fd72 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Thu, 21 Mar 2024 16:35:05 +0000 Subject: [PATCH 24/52] Keep sparse_linear_algebra vague --- .../oneMKL/source/domains/sparse_linear_algebra.inc.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/elements/oneMKL/source/domains/sparse_linear_algebra.inc.rst b/source/elements/oneMKL/source/domains/sparse_linear_algebra.inc.rst index 320be484d..68123a3a2 100644 --- a/source/elements/oneMKL/source/domains/sparse_linear_algebra.inc.rst +++ b/source/elements/oneMKL/source/domains/sparse_linear_algebra.inc.rst @@ -13,7 +13,7 @@ Sparse Linear Algebra Algebra routines using SYCL. :ref:`onemkl_spblas` provides basic operations on sparse vectors and - matrices, and separates them into three stages: query of the external + matrices. Most operations are split into three stages: query of the external workspace size, optimization stage and execution. For a given configuration, the first two stages would typically be called once for a set of input arguments and the execution stage may be called multiple times. During the From 81b8be55f336b40be500d46c0809cb07bd0a5c34 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Fri, 22 Mar 2024 13:46:33 +0000 Subject: [PATCH 25/52] Restrict workspace from being sub-buffers --- .../source/domains/spblas/operations/spmm.rst | 14 ++++++++------ .../source/domains/spblas/operations/spmv.rst | 14 ++++++++------ .../source/domains/spblas/operations/spsv.rst | 14 ++++++++------ 3 files changed, 24 insertions(+), 18 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst index 1a44c0f84..f51b1a5b0 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst @@ -349,12 +349,14 @@ spmm Output buffer size in bytes. workspace - Workspace buffer or USM pointer, must be at least of size - ``temp_buffer_size`` bytes. If it is a buffer, its lifetime is extended - until the :ref:`spmm descriptor` is released. If - it is a USM pointer, it must not be free'd until ``spmm`` has completed. - The data must be accessible on the device and the address aligned on the - size of the handles' data type. + | 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 :ref:`spmm + descriptor` is released. The workspace cannot + be a sub-buffer. + | If it is a USM pointer, it must not be free'd until ``spmm`` has + completed. The data must be accessible on the device. dependencies List of events to depend on before starting asynchronous tasks that access diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst index 336db2c66..498cbd938 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst @@ -327,12 +327,14 @@ spmv Output buffer size in bytes. workspace - Workspace buffer or USM pointer, must be at least of size - ``temp_buffer_size`` bytes. If it is a buffer, its lifetime is extended - until the :ref:`spmv descriptor` is released. If - it is a USM pointer, it must not be free'd until ``spmv`` has completed. - The data must be accessible on the device and the address aligned on the - size of the handles' data type. + | 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 :ref:`spmv + descriptor` is released. The workspace cannot + be a sub-buffer. + | If it is a USM pointer, it must not be free'd until ``spmv`` has + completed. The data must be accessible on the device. dependencies List of events to depend on before starting asynchronous tasks that access diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst index 4f19ba17f..5ecf891be 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst @@ -290,12 +290,14 @@ spsv Output buffer size in bytes. workspace - Workspace buffer or USM pointer, must be at least of size - ``temp_buffer_size`` bytes. If it is a buffer, its lifetime is extended - until the :ref:`spsv descriptor` is released. If - it is a USM pointer, it must not be free'd until ``spsv`` has completed. - The data must be accessible on the device and the address aligned on the - size of the handles' data type. + | 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 :ref:`spsv + descriptor` is released. The workspace cannot + be a sub-buffer. + | If it is a USM pointer, it must not be free'd until ``spsv`` has + completed. The data must be accessible on the device. dependencies List of events to depend on before starting asynchronous tasks that access From 652bfe7592a554cd033c894074a20d391d9d7883 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Thu, 4 Apr 2024 20:22:00 +0100 Subject: [PATCH 26/52] Add no_optimize_alg and remove algorithms tables --- .../source/domains/spblas/operations/spmm.rst | 60 ++++--------------- .../source/domains/spblas/operations/spmv.rst | 48 ++++----------- .../source/domains/spblas/operations/spsv.rst | 23 ++++--- 3 files changed, 33 insertions(+), 98 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst index f51b1a5b0..db1716ae6 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst @@ -157,6 +157,7 @@ spmm_alg enum class spmm_alg { default_alg, + no_optimize_alg, coo_alg1, coo_alg2, coo_alg3, @@ -168,55 +169,16 @@ spmm_alg } -.. list-table:: - :header-rows: 1 - :widths: 10 30 45 - - * - Value - - Description - - Backend equivalent - * - ``default_alg`` - - Default algorithm. - - | MKL: N/A - | cuSPARSE: ``CUSPARSE_SPMM_ALG_DEFAULT`` - | rocSPARSE: ``rocsparse_spmm_alg_default`` - * - ``coo_alg1`` - - Should provide best performance for COO format, small ``nnz`` and - column-major layout. - - | MKL: N/A - | cuSPARSE: ``CUSPARSE_SPMM_COO_ALG1`` - | rocSPARSE: ``rocsparse_spmm_alg_coo_segmented`` - * - ``coo_alg2`` - - Should provide best performance for COO format and column-major layout. - Produces deterministic results. - - | MKL: N/A - | cuSPARSE: ``CUSPARSE_SPMM_COO_ALG2`` - | rocSPARSE: ``rocsparse_spmm_alg_coo_atomic`` - * - ``coo_alg3`` - - Should provide best performance for COO format and large ``nnz``. - - | MKL: N/A - | cuSPARSE: ``CUSPARSE_SPMM_COO_ALG3`` - | rocSPARSE: ``rocsparse_spmm_alg_coo_segmented_atomic`` - * - ``coo_alg4`` - - Should provide best performance for COO format and row-major layout. - - | MKL: N/A - | cuSPARSE: ``CUSPARSE_SPMM_COO_ALG4`` - | rocSPARSE: N/A - * - ``csr_alg1`` - - Should provide best performance for CSR format and column-major layout. - - | MKL: N/A - | cuSPARSE: ``CUSPARSE_SPMM_CSR_ALG1`` - | rocSPARSE: ``rocsparse_spmm_alg_csr`` - * - ``csr_alg2`` - - Should provide best performance for CSR format and row-major layout. - - | MKL: N/A - | cuSPARSE: ``CUSPARSE_SPMM_CSR_ALG2`` - | rocSPARSE: ``rocsparse_spmm_alg_csr_row_split`` - * - ``csr_alg3`` - - Deterministic algorithm for CSR format. - - | MKL: N/A - | cuSPARSE: ``CUSPARSE_SPMM_CSR_ALG3`` - | rocSPARSE: ``rocsparse_spmm_alg_csr_merge`` +.. container:: section + + .. rubric:: 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. .. _onemkl_sparse_spmm: diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst index 498cbd938..e0179fa99 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst @@ -157,6 +157,7 @@ spmv_alg enum class spmv_alg { default_alg, + no_optimize_alg, coo_alg1, coo_alg2, csr_alg1, @@ -166,43 +167,16 @@ spmv_alg } -.. list-table:: - :header-rows: 1 - :widths: 10 30 45 - - * - Value - - Description - - Backend equivalent - * - ``default_alg`` - - Default algorithm. - - | MKL: N/A - | cuSPARSE: ``CUSPARSE_SPMV_ALG_DEFAULT`` - | rocSPARSE: ``rocsparse_spmv_alg_default`` - * - ``coo_alg1`` - - Default algorithm for COO format. - - | MKL: N/A - | cuSPARSE: ``CUSPARSE_SPMV_COO_ALG1`` - | rocSPARSE: ``rocsparse_spmv_alg_coo`` - * - ``coo_alg2`` - - Deterministic algorithm for COO format. - - | MKL: N/A - | cuSPARSE: ``CUSPARSE_SPMV_COO_ALG2`` - | rocSPARSE: ``rocsparse_spmv_alg_coo_atomic`` - * - ``csr_alg1`` - - Default algorithm for CSR format. - - | MKL: N/A - | cuSPARSE: ``CUSPARSE_SPMV_CSR_ALG1`` - | rocSPARSE: ``rocsparse_spmv_alg_csr_adaptive`` - * - ``csr_alg2`` - - Deterministic algorithm for CSR format. - - | MKL: N/A - | cuSPARSE: ``CUSPARSE_SPMV_CSR_ALG2`` - | rocSPARSE: ``rocsparse_spmv_alg_csr_stream`` - * - ``csr_alg3`` - - LRB variant of the algorithm for CSR format. - - | MKL: N/A - | cuSPARSE: N/A - | rocSPARSE: ``rocsparse_spmv_alg_csr_lrb`` +.. container:: section + + .. rubric:: 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. .. _onemkl_sparse_spmv: diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst index 5ecf891be..ebc17a9fc 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst @@ -158,22 +158,21 @@ spsv_alg enum class spsv_alg { default_alg, + no_optimize_alg, }; } -.. list-table:: - :header-rows: 1 - :widths: 10 30 45 - - * - Value - - Description - - Backend equivalent - * - ``default_alg`` - - Default algorithm. - - | MKL: N/A - | cuSPARSE: ``CUSPARSE_SPSV_ALG_DEFAULT`` - | rocSPARSE: ``rocsparse_spsv_alg_default`` +.. container:: section + + .. rubric:: 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. .. _onemkl_sparse_spsv: From c22684f57c4b8758be4fd877c0dea999bc248b86 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Thu, 4 Apr 2024 20:26:57 +0100 Subject: [PATCH 27/52] Remove trailing commas --- .../oneMKL/source/domains/spblas/operations/spmm.rst | 12 ++++-------- .../oneMKL/source/domains/spblas/operations/spmv.rst | 12 ++++-------- .../oneMKL/source/domains/spblas/operations/spsv.rst | 12 ++++-------- 3 files changed, 12 insertions(+), 24 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst index db1716ae6..5efd14a09 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst @@ -203,8 +203,7 @@ spmm oneapi::mkl::sparse::dense_matrix_handle_t C_handle, oneapi::mkl::sparse::spmm_alg alg, oneapi::mkl::sparse::spmm_descr_t spmm_descr, - std::size_t &temp_buffer_size, - ); + std::size_t &temp_buffer_size); void spmm_optimize( sycl::queue &queue, @@ -218,8 +217,7 @@ spmm oneapi::mkl::sparse::dense_matrix_handle_t C_handle, oneapi::mkl::sparse::spmm_alg alg, oneapi::mkl::sparse::spmm_descr_t spmm_descr, - sycl::buffer workspace, - ); + sycl::buffer workspace); sycl::event spmm_optimize( sycl::queue &queue, @@ -234,8 +232,7 @@ spmm oneapi::mkl::sparse::spmm_alg alg, oneapi::mkl::sparse::spmm_descr_t spmm_descr, void* workspace, - const std::vector &dependencies = {}, - ); + const std::vector &dependencies = {}); sycl::event spmm( sycl::queue &queue, @@ -249,8 +246,7 @@ spmm oneapi::mkl::sparse::dense_matrix_handle_t C_handle, oneapi::mkl::sparse::spmm_alg alg, oneapi::mkl::sparse::spmm_descr_t spmm_descr, - const std::vector &dependencies = {}, - ); + const std::vector &dependencies = {}); } diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst index e0179fa99..13ecc9fd1 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst @@ -200,8 +200,7 @@ spmv oneapi::mkl::sparse::dense_vector_handle_t y_handle, oneapi::mkl::sparse::spmv_alg alg, oneapi::mkl::sparse::spmv_descr_t spmv_descr, - std::size_t &temp_buffer_size, - ); + std::size_t &temp_buffer_size); void spmv_optimize( sycl::queue &queue, @@ -214,8 +213,7 @@ spmv oneapi::mkl::sparse::dense_vector_handle_t y_handle, oneapi::mkl::sparse::spmv_alg alg, oneapi::mkl::sparse::spmv_descr_t spmv_descr, - sycl::buffer workspace, - ); + sycl::buffer workspace); sycl::event spmv_optimize( sycl::queue &queue, @@ -229,8 +227,7 @@ spmv oneapi::mkl::sparse::spmv_alg alg, oneapi::mkl::sparse::spmv_descr_t spmv_descr, void* workspace, - const std::vector &dependencies = {}, - ); + const std::vector &dependencies = {}); sycl::event spmv( sycl::queue &queue, @@ -243,8 +240,7 @@ spmv oneapi::mkl::sparse::dense_vector_handle_t y_handle, oneapi::mkl::sparse::spmv_alg alg, oneapi::mkl::sparse::spmv_descr_t spmv_descr, - const std::vector &dependencies = {}, - ); + const std::vector &dependencies = {}); } diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst index ebc17a9fc..842ef8d9e 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst @@ -195,8 +195,7 @@ spsv oneapi::mkl::sparse::dense_vector_handle_t y_handle, oneapi::mkl::sparse::spsv_alg alg, oneapi::mkl::sparse::spsv_descr_t spsv_descr, - std::size_t &temp_buffer_size, - ); + std::size_t &temp_buffer_size); void spsv_optimize( sycl::queue &queue, @@ -208,8 +207,7 @@ spsv oneapi::mkl::sparse::dense_vector_handle_t y_handle, oneapi::mkl::sparse::spsv_alg alg, oneapi::mkl::sparse::spsv_descr_t spsv_descr, - sycl::buffer workspace, - ); + sycl::buffer workspace); sycl::event spsv_optimize( sycl::queue &queue, @@ -222,8 +220,7 @@ spsv oneapi::mkl::sparse::spsv_alg alg, oneapi::mkl::sparse::spsv_descr_t spsv_descr, void* workspace, - const std::vector &dependencies = {}, - ); + const std::vector &dependencies = {}); sycl::event spsv( sycl::queue &queue, @@ -235,8 +232,7 @@ spsv oneapi::mkl::sparse::dense_vector_handle_t y_handle, oneapi::mkl::sparse::spsv_alg alg, oneapi::mkl::sparse::spsv_descr_t spsv_descr, - const std::vector &dependencies = {}, - ); + const std::vector &dependencies = {}); } From 02013d5e70d92cb25284f64da5413132e1045dc5 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Fri, 5 Apr 2024 14:09:06 +0100 Subject: [PATCH 28/52] Make destroy and release functions aynchronous --- .../data_types/destroy_dense_matrix.rst | 16 ++++++++++++++-- .../data_types/destroy_dense_vector.rst | 16 ++++++++++++++-- .../data_types/destroy_sparse_matrix.rst | 19 ++++++++++++++++--- .../source/domains/spblas/operations/spmm.rst | 16 ++++++++++++++-- .../source/domains/spblas/operations/spmv.rst | 16 ++++++++++++++-- .../source/domains/spblas/operations/spsv.rst | 16 ++++++++++++++-- 6 files changed, 86 insertions(+), 13 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/destroy_dense_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/destroy_dense_matrix.rst index 90ea9844c..6b49bbaa4 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/destroy_dense_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/destroy_dense_matrix.rst @@ -24,8 +24,9 @@ If a USM pointer was provided, the data is not free'd. namespace oneapi::mkl::sparse { - void destroy_dense_matrix (sycl::queue &queue, - oneapi::mkl::sparse::dense_matrix_handle_t dmhandle); + sycl::event destroy_dense_matrix (sycl::queue &queue, + oneapi::mkl::sparse::dense_matrix_handle_t dmhandle, + const std::vector &dependencies = {}); } @@ -39,6 +40,17 @@ If a USM pointer was provided, the data is not free'd. dmhandle Handle initialized with :ref:`onemkl_sparse_create_dense_matrix`. + dependencies + List of events to depend on before starting asynchronous tasks that access + data on the device. Defaults to no dependencies. + +.. container:: section + + .. rubric:: Return Values + + Output event that can be waited upon or added as a dependency for the + completion of the function. + .. container:: section .. rubric:: Throws diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/destroy_dense_vector.rst b/source/elements/oneMKL/source/domains/spblas/data_types/destroy_dense_vector.rst index 5096d9b90..651fc9f66 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/destroy_dense_vector.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/destroy_dense_vector.rst @@ -24,8 +24,9 @@ If a USM pointer was provided, the data is not free'd. namespace oneapi::mkl::sparse { - void destroy_dense_vector (sycl::queue &queue, - oneapi::mkl::sparse::dense_vector_handle_t dvhandle); + sycl::event destroy_dense_vector (sycl::queue &queue, + oneapi::mkl::sparse::dense_vector_handle_t dvhandle, + const std::vector &dependencies = {}); } @@ -39,6 +40,17 @@ If a USM pointer was provided, the data is not free'd. dvhandle Handle initialized with :ref:`onemkl_sparse_create_dense_vector`. + dependencies + List of events to depend on before starting asynchronous tasks that access + data on the device. Defaults to no dependencies. + +.. container:: section + + .. rubric:: Return Values + + Output event that can be waited upon or added as a dependency for the + completion of the function. + .. container:: section .. rubric:: Throws diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/destroy_sparse_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/destroy_sparse_matrix.rst index d319d5021..e1ec6bbfe 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/destroy_sparse_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/destroy_sparse_matrix.rst @@ -24,8 +24,9 @@ If a USM pointer was provided, the data is not free'd. namespace oneapi::mkl::sparse { - void destroy_sparse_matrix (sycl::queue &queue, - oneapi::mkl::sparse::matrix_handle_t smhandle); + sycl::event destroy_sparse_matrix (sycl::queue &queue, + oneapi::mkl::sparse::matrix_handle_t smhandle, + const std::vector &dependencies = {}); } @@ -37,7 +38,19 @@ If a USM pointer was provided, the data is not free'd. The SYCL command queue which will be used for SYCL kernels execution. smhandle - Handle initialized with :ref:`onemkl_sparse_create_csr_matrix` or :ref:`onemkl_sparse_create_coo_matrix`. + Handle initialized with :ref:`onemkl_sparse_create_csr_matrix` or + :ref:`onemkl_sparse_create_coo_matrix`. + + dependencies + List of events to depend on before starting asynchronous tasks that access + data on the device. Defaults to no dependencies. + +.. container:: section + + .. rubric:: Return Values + + Output event that can be waited upon or added as a dependency for the + completion of the function. .. container:: section diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst index 5efd14a09..9c4c2af74 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst @@ -116,8 +116,9 @@ release_spmm_descr namespace oneapi::mkl::sparse { - void release_spmm_descr (sycl::queue &queue, - oneapi::mkl::sparse::spmm_descr_t spmm_descr); + sycl::event release_spmm_descr (sycl::queue &queue, + oneapi::mkl::sparse::spmm_descr_t spmm_descr, + const std::vector &dependencies = {}); } @@ -131,6 +132,17 @@ release_spmm_descr spmm_descr Descriptor initialized with ``init_spmm_descr``. + dependencies + List of events to depend on before starting asynchronous tasks that access + data on the device. Defaults to no dependencies. + +.. container:: section + + .. rubric:: Return Values + + Output event that can be waited upon or added as a dependency for the + completion of the function. + .. container:: section .. rubric:: Throws diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst index 13ecc9fd1..8e02eacbd 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst @@ -116,8 +116,9 @@ release_spmv_descr namespace oneapi::mkl::sparse { - void release_spmv_descr (sycl::queue &queue, - oneapi::mkl::sparse::spmv_descr_t spmv_descr); + sycl::event release_spmv_descr (sycl::queue &queue, + oneapi::mkl::sparse::spmv_descr_t spmv_descr, + const std::vector &dependencies = {}); } @@ -131,6 +132,17 @@ release_spmv_descr spmv_descr Descriptor initialized with ``init_spmv_descr``. + dependencies + List of events to depend on before starting asynchronous tasks that access + data on the device. Defaults to no dependencies. + +.. container:: section + + .. rubric:: Return Values + + Output event that can be waited upon or added as a dependency for the + completion of the function. + .. container:: section .. rubric:: Throws diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst index 842ef8d9e..fca134e80 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst @@ -117,8 +117,9 @@ release_spsv_descr namespace oneapi::mkl::sparse { - void release_spsv_descr (sycl::queue &queue, - oneapi::mkl::sparse::spsv_descr_t spsv_descr); + sycl::event release_spsv_descr (sycl::queue &queue, + oneapi::mkl::sparse::spsv_descr_t spsv_descr, + const std::vector &dependencies = {}); } @@ -132,6 +133,17 @@ release_spsv_descr 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. + +.. container:: section + + .. rubric:: Return Values + + Output event that can be waited upon or added as a dependency for the + completion of the function. + .. container:: section .. rubric:: Throws From b4c2a467f235d21df79e7efd8216e665d4357fdf Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Fri, 5 Apr 2024 14:48:55 +0100 Subject: [PATCH 29/52] Update sorted description --- .../domains/spblas/data_types/set_matrix_properties.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_properties.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_properties.rst index db6b502a1..73d654e0f 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_properties.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_properties.rst @@ -39,8 +39,12 @@ Matrix properties the matrix is square, the user data contain both lower and upper triangular regions, and that its transpose is equal to itself. * - ``sorted`` - - Guarantees that the column indices are sorted for a given row. Only - available for the CSR format. TODO: Confirm the description. + - | Guarantees that the user-provided matrix data has some sorting + property. + | For CSR this guarantees that the column indices are sorted in + ascending order for a given row. + | For COO this guarantees that that the row indices are sorted in + ascending order. set_matrix_properties --------------------- From 0f7c767fb6e936a5d0edbed5034dfaf779a9b244 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Fri, 5 Apr 2024 15:10:44 +0100 Subject: [PATCH 30/52] Remove restriction on create_*_matrix to support multiple calls with the same handle --- .../domains/spblas/data_types/create_coo_matrix.rst | 11 +++-------- .../domains/spblas/data_types/create_csr_matrix.rst | 11 +++-------- 2 files changed, 6 insertions(+), 16 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst index c5aceb040..8c0b9d513 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst @@ -28,14 +28,9 @@ addition (sparse matrix + sparse matrix = sparse matrix), and multiplication of two sparse matrices, the number of non-zero elements in the output sparse matrix is not known in advance and must be calculated as part of the operation API. Such APIs are currently not a part of the current oneMKL Specification, but will -be added in the future. Therefore, it is important for the ``create_coo_matrix`` -API to be able to handle multiple calls to build the sparse matrix as function -arguments become known and arrays are allocated with the correct sizes. In -particular, the ``create_coo_matrix`` API must handle the case where the number -of non-zero elements in the matrix are unknown and the matrix arrays are -``nullptr`` or zero-sized ``sycl::buffer`` objects as applicable. This behavior -is currently left to be implementation-defined, but may be clarified in the -oneMKL Specification in the future. +be added in the future. This behavior is currently left to be +implementation-defined, but may be clarified in the oneMKL Specification in the +future. See :ref:`onemkl_sparse_matrix_handle`. diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst index 59c297f89..6c5772cb6 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst @@ -28,14 +28,9 @@ addition (sparse matrix + sparse matrix = sparse matrix), and multiplication of two sparse matrices, the number of non-zero elements in the output sparse matrix is not known in advance and must be calculated as part of the operation API. Such APIs are currently not a part of the current oneMKL Specification, but will -be added in the future. Therefore, it is important for the ``create_csr_matrix`` -API to be able to handle multiple calls to build the sparse matrix as function -arguments become known and arrays are allocated with the correct sizes. In -particular, the ``create_csr_matrix`` API must handle the case where the number -of non-zero elements in the matrix are unknown and the matrix arrays are -``nullptr`` or zero-sized ``sycl::buffer`` objects as applicable. This behavior -is currently left to be implementation-defined, but may be clarified in the -oneMKL Specification in the future. +be added in the future. This behavior is currently left to be +implementation-defined, but may be clarified in the oneMKL Specification in the +future. See :ref:`onemkl_sparse_matrix_handle`. From 15139cc39ec308179725fd368f473f0d29d57ed2 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Fri, 5 Apr 2024 15:21:37 +0100 Subject: [PATCH 31/52] Make uplo_view description match with diag_view --- source/elements/oneMKL/source/domains/spblas/matrix_view.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/matrix_view.rst b/source/elements/oneMKL/source/domains/spblas/matrix_view.rst index 000ba1e78..ca9042002 100644 --- a/source/elements/oneMKL/source/domains/spblas/matrix_view.rst +++ b/source/elements/oneMKL/source/domains/spblas/matrix_view.rst @@ -84,8 +84,8 @@ matrix_view See :ref:`onemkl_sparse_matrix_descriptor`, :ref:`onemkl_enum_uplo` and :ref:`onemkl_enum_diag` fot a description of the members. - The ``uplo_view`` member is only used if ``type_view`` is ``symmetric``, - ``hermitian`` or ``triangular``. + The ``uplo_view`` member is ignored if ``type_view`` is ``general`` or + ``diagonal``. The ``diag_view`` member is ignored if ``type_view`` is ``general``. From 7c34155ceaf5051f4d22479772108294441a8f04 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Fri, 5 Apr 2024 16:49:33 +0100 Subject: [PATCH 32/52] Rephrase operation descriptions --- .../source/domains/spblas/operations/spmm.rst | 13 +++++++------ .../source/domains/spblas/operations/spmv.rst | 15 ++++++++------- .../source/domains/spblas/operations/spsv.rst | 14 +++++++------- 3 files changed, 22 insertions(+), 20 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst index 9c4c2af74..9162d8aaa 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst @@ -18,9 +18,13 @@ product defined as: C \leftarrow \alpha \cdot \text{op}(A) \cdot \text{op}(B) + \beta \cdot C -where :math:`\alpha` and :math:`\beta` are scalars, :math:`A` is a sparse -matrix, :math:`B` and :math:`C` are dense matrices, :math:`\text{op}()` is a -matrix modifier for :math:`A` and :math:`B` using the following description: + +| where: +| :math:`\alpha` and :math:`\beta` are scalars, +| :math:`C` is a dense matrix of size ``m``-by-``n``, +| :math:`\text{op}(A)` is a transformed sparse matrix of size ``m``-by-``k``, +| :math:`\text{op}(B)` is a transformed dense matrix of size ``k``-by-``n``, +| :math:`\text{op}()` is the transform operation using the following description: .. math:: @@ -29,9 +33,6 @@ matrix modifier for :math:`A` and :math:`B` using the following description: A^\mathsf{H},& \text{oneapi::mkl::transpose::conjtrans} \end{cases} -and :math:`\text{op}(A)` is an ``m``-by-``k`` matrix , :math:`\text{op}(B)` is -an ``k``-by-``n`` matrix, and :math:`C` is an ``m``-by-``n`` matrix. - .. _onemkl_sparse_spmm_descr: spmm_descr diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst index 8e02eacbd..933e76882 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst @@ -16,11 +16,15 @@ product defined as: .. math:: - y \leftarrow \alpha \cdot \text{op}(A) \cdot x + \beta \cdot y + y \leftarrow \alpha \cdot \text{op}(A) \cdot x + \beta \cdot y -where :math:`\alpha` and :math:`\beta` are scalars, :math:`A` is a sparse -matrix, :math:`x` and :math:`y` are dense vectors, :math:`\text{op}()` is a -matrix modifier for :math:`A` using the following description: + +| where: +| :math:`\alpha` and :math:`\beta` are scalars, +| :math:`x` is a dense vector of size ``n``, +| :math:`y` is a dense vector of size ``m``, +| :math:`\text{op}(A)` is a transformed sparse matrix of size ``m``-by-``n``, +| :math:`\text{op}()` is the transform operation using the following description: .. math:: @@ -29,9 +33,6 @@ matrix modifier for :math:`A` using the following description: A^\mathsf{H},& \text{oneapi::mkl::transpose::conjtrans} \end{cases} -and :math:`\text{op}(A)` is an ``m``-by-``n`` matrix , :math:`x` is a vector of -size ``n`` and :math:`y` is a vector of size ``m``. - .. _onemkl_sparse_spmv_descr: spmv_descr diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst index fca134e80..da442127c 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst @@ -17,11 +17,14 @@ for a square matrix: .. math:: - \text{op}(A) \cdot y \leftarrow \alpha \cdot x + \text{op}(A) \cdot y \leftarrow \alpha \cdot x -where :math:`\alpha` is a scalar, :math:`A` is a triangular sparse matrix, -:math:`x` and :math:`y` are dense vectors, :math:`\text{op}()` is a matrix -modifier for :math:`A` using the following description: + +| where: +| :math:`\alpha` is a scalar, +| :math:`x` and :math:`y` are dense vectors of size ``m``, +| :math:`\text{op}(A)` is a transformed sparse matrix of size ``m``-by-``m``, +| :math:`\text{op}()` is the transform operation using the following description: .. math:: @@ -30,9 +33,6 @@ modifier for :math:`A` using the following description: A^\mathsf{H},& \text{oneapi::mkl::transpose::conjtrans} \end{cases} -and :math:`\text{op}(A)` is an ``m``-by-``m`` matrix , :math:`x` and :math:`y` -are vectors of size ``m``. - .. _onemkl_sparse_spsv_descr: spsv_descr From 3ab3c5e011abe78133fc917617f91325535f64ce Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Sat, 6 Apr 2024 14:53:20 +0100 Subject: [PATCH 33/52] Clarifications on workspace --- .../oneMKL/source/domains/spblas/operations/spmm.rst | 8 ++++---- .../oneMKL/source/domains/spblas/operations/spmv.rst | 8 ++++---- .../oneMKL/source/domains/spblas/operations/spsv.rst | 8 ++++---- 3 files changed, 12 insertions(+), 12 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst index 9162d8aaa..d9268eaa9 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst @@ -324,10 +324,10 @@ spmm ``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 :ref:`spmm - descriptor` is released. The workspace cannot - be a sub-buffer. - | If it is a USM pointer, it must not be free'd until ``spmm`` has - completed. The data must be accessible on the device. + descriptor` is released or the workspace is + reset by ``spmm_optimize``. The workspace cannot be a sub-buffer. + | If it is a USM pointer, it must not be free'd until the corresponding + ``spmm`` has completed. The data must be accessible on the device. dependencies List of events to depend on before starting asynchronous tasks that access diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst index 933e76882..399726bd6 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst @@ -314,10 +314,10 @@ spmv ``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 :ref:`spmv - descriptor` is released. The workspace cannot - be a sub-buffer. - | If it is a USM pointer, it must not be free'd until ``spmv`` has - completed. The data must be accessible on the device. + descriptor` is released or the workspace is + reset by ``spmv_optimize``. The workspace cannot be a sub-buffer. + | If it is a USM pointer, it must not be free'd until the corresponding + ``spmv`` has completed. The data must be accessible on the device. dependencies List of events to depend on before starting asynchronous tasks that access diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst index da442127c..346451d6f 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst @@ -301,10 +301,10 @@ spsv ``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 :ref:`spsv - descriptor` is released. The workspace cannot - be a sub-buffer. - | If it is a USM pointer, it must not be free'd until ``spsv`` has - completed. The data must be accessible on the device. + 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 From 1cbd268c6c39aa2f1464ab5df2cd6e24f6554c1e Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Sat, 6 Apr 2024 14:59:43 +0100 Subject: [PATCH 34/52] Clarify temp_buffer_size is the minimum workspace size --- .../elements/oneMKL/source/domains/spblas/operations/spmm.rst | 4 ++-- .../elements/oneMKL/source/domains/spblas/operations/spmv.rst | 4 ++-- .../elements/oneMKL/source/domains/spblas/operations/spsv.rst | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst index d9268eaa9..72ef5fac2 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst @@ -338,8 +338,8 @@ spmm .. rubric:: Output Parameters temp_buffer_size - Output buffer size in bytes. A temporary workspace of this size must be - allocated to perform the specified spmm. + Output buffer size in bytes. A temporary workspace of at least this size + must be allocated to perform the specified spmm. C_handle Dense matrix handle object representing :math:`C`, result of the ``spmm`` diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst index 399726bd6..bf1660065 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst @@ -328,8 +328,8 @@ spmv .. rubric:: Output Parameters temp_buffer_size - Output buffer size in bytes. A temporary workspace of this size must be - allocated to perform the specified spmv. + Output buffer size in bytes. A temporary workspace of at least this size + must be allocated to perform the specified spmv. y_handle Dense vector handle object representing :math:`y`, result of the ``spmv`` diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst index 346451d6f..a25f7fdc4 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst @@ -315,8 +315,8 @@ spsv .. rubric:: Output Parameters temp_buffer_size - Output buffer size in bytes. A temporary workspace of this size must be - allocated to perform the specified spsv. + 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 :math:`y`, result of the ``spsv`` From d0393b161f14260477a726fb6ab0bb8bfb125a8b Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Sat, 6 Apr 2024 15:01:47 +0100 Subject: [PATCH 35/52] Minor fixes and rewording --- .../source/domains/sparse_linear_algebra.inc.rst | 4 ++-- .../domains/spblas/data_types/create_coo_matrix.rst | 9 ++++----- .../domains/spblas/data_types/create_csr_matrix.rst | 12 ++++++------ .../oneMKL/source/domains/spblas/matrix_view.rst | 2 +- .../oneMKL/source/domains/spblas/operations/spmm.rst | 6 +++--- .../oneMKL/source/domains/spblas/operations/spmv.rst | 6 +++--- 6 files changed, 19 insertions(+), 20 deletions(-) diff --git a/source/elements/oneMKL/source/domains/sparse_linear_algebra.inc.rst b/source/elements/oneMKL/source/domains/sparse_linear_algebra.inc.rst index 68123a3a2..dbb22c377 100644 --- a/source/elements/oneMKL/source/domains/sparse_linear_algebra.inc.rst +++ b/source/elements/oneMKL/source/domains/sparse_linear_algebra.inc.rst @@ -9,8 +9,8 @@ Sparse Linear Algebra .. container:: - The oneAPI Math Kernel Library provides a C++ interface to some Sparse Linear - Algebra routines using SYCL. + The oneAPI Math Kernel Library provides a C++ interface to a set of Sparse + Linear Algebra routines using SYCL. :ref:`onemkl_spblas` provides basic operations on sparse vectors and matrices. Most operations are split into three stages: query of the external diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst index 8c0b9d513..dbb9f71b7 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst @@ -26,11 +26,10 @@ the number of non-zero elements in the sparse matrix as an argument. However, in certain math operations where the output is a sparse matrix, e.g., sparse matrix addition (sparse matrix + sparse matrix = sparse matrix), and multiplication of two sparse matrices, the number of non-zero elements in the output sparse matrix -is not known in advance and must be calculated as part of the operation API. -Such APIs are currently not a part of the current oneMKL Specification, but will -be added in the future. This behavior is currently left to be -implementation-defined, but may be clarified in the oneMKL Specification in the -future. +are not known in advance and must be calculated as part of the operation API. +Such APIs are currently not part of the oneMKL Specification, but will be added +in the future. This behavior is currently left to be implementation-defined, but +may be clarified in the oneMKL Specification in the future. See :ref:`onemkl_sparse_matrix_handle`. diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst index 6c5772cb6..611d3233d 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst @@ -7,7 +7,8 @@ create_csr_matrix ================= -Initializes a ``matrix_handle_t`` object with the provided CSR data. +Initializes a ``matrix_handle_t`` object with the provided Compressed Sparse Row +(CSR) data. .. rubric:: Description and Assumptions @@ -26,11 +27,10 @@ the number of non-zero elements in the sparse matrix as an argument. However, in certain math operations where the output is a sparse matrix, e.g., sparse matrix addition (sparse matrix + sparse matrix = sparse matrix), and multiplication of two sparse matrices, the number of non-zero elements in the output sparse matrix -is not known in advance and must be calculated as part of the operation API. -Such APIs are currently not a part of the current oneMKL Specification, but will -be added in the future. This behavior is currently left to be -implementation-defined, but may be clarified in the oneMKL Specification in the -future. +are not known in advance and must be calculated as part of the operation API. +Such APIs are currently not part of the oneMKL Specification, but will be added +in the future. This behavior is currently left to be implementation-defined, but +may be clarified in the oneMKL Specification in the future. See :ref:`onemkl_sparse_matrix_handle`. diff --git a/source/elements/oneMKL/source/domains/spblas/matrix_view.rst b/source/elements/oneMKL/source/domains/spblas/matrix_view.rst index ca9042002..c69069c58 100644 --- a/source/elements/oneMKL/source/domains/spblas/matrix_view.rst +++ b/source/elements/oneMKL/source/domains/spblas/matrix_view.rst @@ -82,7 +82,7 @@ matrix_view be read without changing the matrix's data. See :ref:`onemkl_sparse_matrix_descriptor`, :ref:`onemkl_enum_uplo` and - :ref:`onemkl_enum_diag` fot a description of the members. + :ref:`onemkl_enum_diag` for a description of the members. The ``uplo_view`` member is ignored if ``type_view`` is ``general`` or ``diagonal``. diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst index 72ef5fac2..f7e0b5549 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst @@ -7,12 +7,12 @@ spmm ==== -Computes a sparse matrix-dense matrix product. +Computes a sparse matrix by dense matrix product. .. rubric:: Description and Assumptions -The ``oneapi::mkl::sparse::spmm`` routine computes a sparse matrix-dense matrix -product defined as: +The ``oneapi::mkl::sparse::spmm`` routine computes a sparse matrix by dense +matrix product defined as: .. math:: diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst index bf1660065..57b542bf0 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst @@ -7,12 +7,12 @@ spmv ==== -Computes a sparse matrix-dense vector product. +Computes a sparse matrix by dense vector product. .. rubric:: Description and Assumptions -The ``oneapi::mkl::sparse::spmv`` routine computes a sparse matrix-dense vector -product defined as: +The ``oneapi::mkl::sparse::spmv`` routine computes a sparse matrix by dense +vector product defined as: .. math:: From 4128a65bcfd5be60fa15d8797e63d7db6fdaa008 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Sat, 6 Apr 2024 15:33:32 +0100 Subject: [PATCH 36/52] Rename create_* and destroy_* functions to init_* and release_* --- .../spblas/data_types/data_handles.rst | 28 ++++----- ...ate_coo_matrix.rst => init_coo_matrix.rst} | 62 +++++++++---------- ...ate_csr_matrix.rst => init_csr_matrix.rst} | 62 +++++++++---------- ...dense_matrix.rst => init_dense_matrix.rst} | 50 +++++++-------- ...dense_vector.rst => init_dense_vector.rst} | 38 ++++++------ ...se_matrix.rst => release_dense_matrix.rst} | 10 +-- ...se_vector.rst => release_dense_vector.rst} | 10 +-- ...e_matrix.rst => release_sparse_matrix.rst} | 12 ++-- .../spblas/data_types/set_coo_matrix_data.rst | 10 +-- .../spblas/data_types/set_csr_matrix_data.rst | 10 +-- .../data_types/set_dense_matrix_data.rst | 8 +-- .../data_types/set_dense_vector_data.rst | 8 +-- 12 files changed, 154 insertions(+), 154 deletions(-) rename source/elements/oneMKL/source/domains/spblas/data_types/{create_coo_matrix.rst => init_coo_matrix.rst} (78%) rename source/elements/oneMKL/source/domains/spblas/data_types/{create_csr_matrix.rst => init_csr_matrix.rst} (77%) rename source/elements/oneMKL/source/domains/spblas/data_types/{create_dense_matrix.rst => init_dense_matrix.rst} (74%) rename source/elements/oneMKL/source/domains/spblas/data_types/{create_dense_vector.rst => init_dense_vector.rst} (77%) rename source/elements/oneMKL/source/domains/spblas/data_types/{destroy_dense_matrix.rst => release_dense_matrix.rst} (86%) rename source/elements/oneMKL/source/domains/spblas/data_types/{destroy_dense_vector.rst => release_dense_vector.rst} (86%) rename source/elements/oneMKL/source/domains/spblas/data_types/{destroy_sparse_matrix.rst => release_sparse_matrix.rst} (84%) diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/data_handles.rst b/source/elements/oneMKL/source/domains/spblas/data_types/data_handles.rst index db348e234..0e0084cfb 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/data_handles.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/data_handles.rst @@ -33,9 +33,9 @@ Dense vector handle See related functions: - - :ref:`onemkl_sparse_create_dense_vector` + - :ref:`onemkl_sparse_init_dense_vector` - :ref:`onemkl_sparse_set_dense_vector_data` - - :ref:`onemkl_sparse_destroy_dense_vector` + - :ref:`onemkl_sparse_release_dense_vector` .. _onemkl_sparse_dense_matrix_handle: @@ -63,9 +63,9 @@ Dense matrix handle See related functions: - - :ref:`onemkl_sparse_create_dense_matrix` + - :ref:`onemkl_sparse_init_dense_matrix` - :ref:`onemkl_sparse_set_dense_matrix_data` - - :ref:`onemkl_sparse_destroy_dense_matrix` + - :ref:`onemkl_sparse_release_dense_matrix` .. _onemkl_sparse_matrix_handle: @@ -93,29 +93,29 @@ Sparse matrix handle See related functions: - - :ref:`onemkl_sparse_create_coo_matrix` - - :ref:`onemkl_sparse_create_csr_matrix` + - :ref:`onemkl_sparse_init_coo_matrix` + - :ref:`onemkl_sparse_init_csr_matrix` - :ref:`onemkl_sparse_set_coo_matrix_data` - :ref:`onemkl_sparse_set_csr_matrix_data` - :ref:`onemkl_sparse_set_matrix_properties` - - :ref:`onemkl_sparse_destroy_sparse_matrix` + - :ref:`onemkl_sparse_release_sparse_matrix` See a description of the supported :ref:`sparse formats`. .. toctree:: :hidden: - create_dense_vector - create_dense_matrix - create_coo_matrix - create_csr_matrix + init_dense_vector + init_dense_matrix + init_coo_matrix + init_csr_matrix + release_dense_vector + release_dense_matrix + release_sparse_matrix set_dense_vector_data set_dense_matrix_data set_coo_matrix_data set_csr_matrix_data - destroy_dense_vector - destroy_dense_matrix - destroy_sparse_matrix set_matrix_properties format-descriptions diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/init_coo_matrix.rst similarity index 78% rename from source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst rename to source/elements/oneMKL/source/domains/spblas/data_types/init_coo_matrix.rst index dbb9f71b7..4ebd1220f 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_coo_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/init_coo_matrix.rst @@ -2,27 +2,27 @@ .. .. SPDX-License-Identifier: CC-BY-4.0 -.. _onemkl_sparse_create_coo_matrix: +.. _onemkl_sparse_init_coo_matrix: -create_coo_matrix -================= +init_coo_matrix +=============== Initializes a ``matrix_handle_t`` object with the provided COO data. .. rubric:: Description and Assumptions -The ``oneapi::mkl::sparse::create_coo_matrix`` function initializes the +The ``oneapi::mkl::sparse::init_coo_matrix`` function initializes the ``matrix_handle_t`` object with the provided data. In the case of buffers, the reference count of the provided buffer is incremented which extends the lifetime of the underlying buffer until the sparse -matrix handle is destroyed with ``destroy_sparse_matrix`` or the data is reset +matrix handle is destroyed with ``release_sparse_matrix`` or the data is reset with ``set_coo_matrix_data``. In the case of USM, the object does not take ownership of the data. -The ``oneapi::mkl::sparse::create_coo_matrix`` function defined below takes in -the number of non-zero elements in the sparse matrix as an argument. However, in +The ``oneapi::mkl::sparse::init_coo_matrix`` function defined below takes in the +number of non-zero elements in the sparse matrix as an argument. However, in certain math operations where the output is a sparse matrix, e.g., sparse matrix addition (sparse matrix + sparse matrix = sparse matrix), and multiplication of two sparse matrices, the number of non-zero elements in the output sparse matrix @@ -33,10 +33,10 @@ may be clarified in the oneMKL Specification in the future. See :ref:`onemkl_sparse_matrix_handle`. -.. _onemkl_sparse_create_coo_matrix_buffer: +.. _onemkl_sparse_init_coo_matrix_buffer: -create_coo_matrix (Buffer version) ----------------------------------- +init_coo_matrix (Buffer version) +-------------------------------- .. rubric:: Syntax @@ -45,15 +45,15 @@ create_coo_matrix (Buffer version) namespace oneapi::mkl::sparse { template - void create_coo_matrix (sycl::queue &queue, - oneapi::mkl::sparse::matrix_handle_t *p_smhandle, - std::int64_t num_rows, - std::int64_t num_cols, - std::int64_t nnz, - index_base index, - sycl::buffer &row_ind, - sycl::buffer &col_ind, - sycl::buffer &val); + void init_coo_matrix (sycl::queue &queue, + oneapi::mkl::sparse::matrix_handle_t *p_smhandle, + std::int64_t num_rows, + std::int64_t num_cols, + std::int64_t nnz, + index_base index, + sycl::buffer &row_ind, + sycl::buffer &col_ind, + sycl::buffer &val); } @@ -138,10 +138,10 @@ create_coo_matrix (Buffer version) | :ref:`oneapi::mkl::unimplemented` | :ref:`oneapi::mkl::unsupported_device` -.. _onemkl_sparse_create_coo_matrix_usm: +.. _onemkl_sparse_init_coo_matrix_usm: -create_coo_matrix (USM version) -------------------------------- +init_coo_matrix (USM version) +----------------------------- .. rubric:: Syntax @@ -150,15 +150,15 @@ create_coo_matrix (USM version) namespace oneapi::mkl::sparse { template - void create_coo_matrix (sycl::queue &queue, - oneapi::mkl::sparse::matrix_handle_t *p_smhandle, - std::int64_t num_rows, - std::int64_t num_cols, - std::int64_t nnz, - index_base index, - indexType *row_ind, - indexType *col_ind, - dataType *val); + void init_coo_matrix (sycl::queue &queue, + oneapi::mkl::sparse::matrix_handle_t *p_smhandle, + std::int64_t num_rows, + std::int64_t num_cols, + std::int64_t nnz, + index_base index, + indexType *row_ind, + indexType *col_ind, + dataType *val); } diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/init_csr_matrix.rst similarity index 77% rename from source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst rename to source/elements/oneMKL/source/domains/spblas/data_types/init_csr_matrix.rst index 611d3233d..a1c37b6b4 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_csr_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/init_csr_matrix.rst @@ -2,28 +2,28 @@ .. .. SPDX-License-Identifier: CC-BY-4.0 -.. _onemkl_sparse_create_csr_matrix: +.. _onemkl_sparse_init_csr_matrix: -create_csr_matrix -================= +init_csr_matrix +=============== Initializes a ``matrix_handle_t`` object with the provided Compressed Sparse Row (CSR) data. .. rubric:: Description and Assumptions -The ``oneapi::mkl::sparse::create_csr_matrix`` function initializes the +The ``oneapi::mkl::sparse::init_csr_matrix`` function initializes the ``matrix_handle_t`` object with the provided data. In the case of buffers, the reference count of the provided buffer is incremented which extends the lifetime of the underlying buffer until the sparse -matrix handle is destroyed with ``destroy_sparse_matrix`` or the data is reset +matrix handle is destroyed with ``release_sparse_matrix`` or the data is reset with ``set_csr_matrix_data``. In the case of USM, the object does not take ownership of the data. -The ``oneapi::mkl::sparse::create_csr_matrix`` function defined below takes in -the number of non-zero elements in the sparse matrix as an argument. However, in +The ``oneapi::mkl::sparse::init_csr_matrix`` function defined below takes in the +number of non-zero elements in the sparse matrix as an argument. However, in certain math operations where the output is a sparse matrix, e.g., sparse matrix addition (sparse matrix + sparse matrix = sparse matrix), and multiplication of two sparse matrices, the number of non-zero elements in the output sparse matrix @@ -34,10 +34,10 @@ may be clarified in the oneMKL Specification in the future. See :ref:`onemkl_sparse_matrix_handle`. -.. _onemkl_sparse_create_csr_matrix_buffer: +.. _onemkl_sparse_init_csr_matrix_buffer: -create_csr_matrix (Buffer version) ----------------------------------- +init_csr_matrix (Buffer version) +-------------------------------- .. rubric:: Syntax @@ -46,15 +46,15 @@ create_csr_matrix (Buffer version) namespace oneapi::mkl::sparse { template - void create_csr_matrix (sycl::queue &queue, - oneapi::mkl::sparse::matrix_handle_t *p_smhandle, - std::int64_t num_rows, - std::int64_t num_cols, - std::int64_t nnz, - index_base index, - sycl::buffer &row_ptr, - sycl::buffer &col_ind, - sycl::buffer &val); + void init_csr_matrix (sycl::queue &queue, + oneapi::mkl::sparse::matrix_handle_t *p_smhandle, + std::int64_t num_rows, + std::int64_t num_cols, + std::int64_t nnz, + index_base index, + sycl::buffer &row_ptr, + sycl::buffer &col_ind, + sycl::buffer &val); } @@ -138,10 +138,10 @@ create_csr_matrix (Buffer version) | :ref:`oneapi::mkl::unimplemented` | :ref:`oneapi::mkl::unsupported_device` -.. _onemkl_sparse_create_csr_matrix_usm: +.. _onemkl_sparse_init_csr_matrix_usm: -create_csr_matrix (USM version) -------------------------------- +init_csr_matrix (USM version) +----------------------------- .. rubric:: Syntax @@ -150,15 +150,15 @@ create_csr_matrix (USM version) namespace oneapi::mkl::sparse { template - void create_csr_matrix (sycl::queue &queue, - oneapi::mkl::sparse::matrix_handle_t *p_smhandle, - std::int64_t num_rows, - std::int64_t num_cols, - std::int64_t nnz, - index_base index, - indexType *row_ptr, - indexType *col_ind, - dataType *val); + void init_csr_matrix (sycl::queue &queue, + oneapi::mkl::sparse::matrix_handle_t *p_smhandle, + std::int64_t num_rows, + std::int64_t num_cols, + std::int64_t nnz, + index_base index, + indexType *row_ptr, + indexType *col_ind, + dataType *val); } diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/init_dense_matrix.rst similarity index 74% rename from source/elements/oneMKL/source/domains/spblas/data_types/create_dense_matrix.rst rename to source/elements/oneMKL/source/domains/spblas/data_types/init_dense_matrix.rst index 60d4cb598..ebcb4d553 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/init_dense_matrix.rst @@ -2,31 +2,31 @@ .. .. SPDX-License-Identifier: CC-BY-4.0 -.. _onemkl_sparse_create_dense_matrix: +.. _onemkl_sparse_init_dense_matrix: -create_dense_matrix -=================== +init_dense_matrix +================= Initializes a ``dense_matrix_handle_t`` object with the provided data. .. rubric:: Description and Assumptions -The ``oneapi::mkl::sparse::create_dense_matrix`` function initializes the +The ``oneapi::mkl::sparse::init_dense_matrix`` function initializes the ``dense_matrix_handle_t`` object with the provided data. In the case of buffers, the reference count of the provided buffer is incremented which extends the lifetime of the underlying buffer until the dense -matrix handle is destroyed with ``destroy_dense_matrix`` or the data is reset +matrix handle is destroyed with ``release_dense_matrix`` or the data is reset with ``set_dense_matrix_data``. In the case of USM, the object does not take ownership of the data. See :ref:`onemkl_sparse_dense_matrix_handle`. -.. _onemkl_sparse_create_dense_matrix_buffer: +.. _onemkl_sparse_init_dense_matrix_buffer: -create_dense_matrix (Buffer version) ------------------------------------- +init_dense_matrix (Buffer version) +---------------------------------- .. rubric:: Syntax @@ -35,13 +35,13 @@ create_dense_matrix (Buffer version) namespace oneapi::mkl::sparse { template - void create_dense_matrix (sycl::queue &queue, - oneapi::mkl::sparse::dense_matrix_handle_t *p_dmhandle, - std::int64_t num_rows, - std::int64_t num_cols, - std::int64_t ld, - layout dense_layout, - sycl::buffer &val); + void init_dense_matrix (sycl::queue &queue, + oneapi::mkl::sparse::dense_matrix_handle_t *p_dmhandle, + std::int64_t num_rows, + std::int64_t num_cols, + std::int64_t ld, + layout dense_layout, + sycl::buffer &val); } @@ -105,10 +105,10 @@ create_dense_matrix (Buffer version) | :ref:`oneapi::mkl::unimplemented` | :ref:`oneapi::mkl::unsupported_device` -.. _onemkl_sparse_create_dense_matrix_usm: +.. _onemkl_sparse_init_dense_matrix_usm: -create_dense_matrix (USM version) ---------------------------------- +init_dense_matrix (USM version) +------------------------------- .. rubric:: Syntax @@ -117,13 +117,13 @@ create_dense_matrix (USM version) namespace oneapi::mkl::sparse { template - void create_dense_matrix (sycl::queue &queue, - oneapi::mkl::sparse::dense_matrix_handle_t *p_dmhandle, - std::int64_t num_rows, - std::int64_t num_cols, - std::int64_t ld, - layout dense_layout, - dataType *val); + void init_dense_matrix (sycl::queue &queue, + oneapi::mkl::sparse::dense_matrix_handle_t *p_dmhandle, + std::int64_t num_rows, + std::int64_t num_cols, + std::int64_t ld, + layout dense_layout, + dataType *val); } diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_vector.rst b/source/elements/oneMKL/source/domains/spblas/data_types/init_dense_vector.rst similarity index 77% rename from source/elements/oneMKL/source/domains/spblas/data_types/create_dense_vector.rst rename to source/elements/oneMKL/source/domains/spblas/data_types/init_dense_vector.rst index f282ecd7e..2fe1f6a7e 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/create_dense_vector.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/init_dense_vector.rst @@ -2,31 +2,31 @@ .. .. SPDX-License-Identifier: CC-BY-4.0 -.. _onemkl_sparse_create_dense_vector: +.. _onemkl_sparse_init_dense_vector: -create_dense_vector -=================== +init_dense_vector +================= Initializes a ``dense_vector_handle_t`` object with the provided data. .. rubric:: Description and Assumptions -The ``oneapi::mkl::sparse::create_dense_vector`` function initializes the +The ``oneapi::mkl::sparse::init_dense_vector`` function initializes the ``dense_vector_handle_t`` object with the provided data. In the case of buffers, the reference count of the provided buffer is incremented which extends the lifetime of the underlying buffer until the dense -vector handle is destroyed with ``destroy_dense_vector`` or the data is reset +vector handle is destroyed with ``release_dense_vector`` or the data is reset with ``set_dense_vector_data``. In the case of USM, the object does not take ownership of the data. See :ref:`onemkl_sparse_dense_vector_handle`. -.. _onemkl_sparse_create_dense_vector_buffer: +.. _onemkl_sparse_init_dense_vector_buffer: -create_dense_vector (Buffer version) ------------------------------------- +init_dense_vector (Buffer version) +---------------------------------- .. rubric:: Syntax @@ -35,10 +35,10 @@ create_dense_vector (Buffer version) namespace oneapi::mkl::sparse { template - void create_dense_vector (sycl::queue &queue, - oneapi::mkl::sparse::dense_vector_handle_t *p_dvhandle, - std::int64_t size, - sycl::buffer &val); + void init_dense_vector (sycl::queue &queue, + oneapi::mkl::sparse::dense_vector_handle_t *p_dvhandle, + std::int64_t size, + sycl::buffer &val); } @@ -90,10 +90,10 @@ create_dense_vector (Buffer version) | :ref:`oneapi::mkl::unimplemented` | :ref:`oneapi::mkl::unsupported_device` -.. _onemkl_sparse_create_dense_vector_usm: +.. _onemkl_sparse_init_dense_vector_usm: -create_dense_vector (USM version) ---------------------------------- +init_dense_vector (USM version) +------------------------------- .. rubric:: Syntax @@ -102,10 +102,10 @@ create_dense_vector (USM version) namespace oneapi::mkl::sparse { template - void create_dense_vector (sycl::queue &queue, - oneapi::mkl::sparse::dense_vector_handle_t *p_dvhandle, - std::int64_t size, - dataType *val); + void init_dense_vector (sycl::queue &queue, + oneapi::mkl::sparse::dense_vector_handle_t *p_dvhandle, + std::int64_t size, + dataType *val); } diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/destroy_dense_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/release_dense_matrix.rst similarity index 86% rename from source/elements/oneMKL/source/domains/spblas/data_types/destroy_dense_matrix.rst rename to source/elements/oneMKL/source/domains/spblas/data_types/release_dense_matrix.rst index 6b49bbaa4..2d77606e1 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/destroy_dense_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/release_dense_matrix.rst @@ -2,16 +2,16 @@ .. .. SPDX-License-Identifier: CC-BY-4.0 -.. _onemkl_sparse_destroy_dense_matrix: +.. _onemkl_sparse_release_dense_matrix: -destroy_dense_matrix +release_dense_matrix ==================== Destroys a ``dense_matrix_handle_t`` object. .. rubric:: Description and Assumptions -The ``oneapi::mkl::sparse::destroy_dense_matrix`` function frees the resources +The ``oneapi::mkl::sparse::release_dense_matrix`` function frees the resources allocated for the handle. If a buffer was provided, its reference count is decremented. @@ -24,7 +24,7 @@ If a USM pointer was provided, the data is not free'd. namespace oneapi::mkl::sparse { - sycl::event destroy_dense_matrix (sycl::queue &queue, + sycl::event release_dense_matrix (sycl::queue &queue, oneapi::mkl::sparse::dense_matrix_handle_t dmhandle, const std::vector &dependencies = {}); @@ -38,7 +38,7 @@ If a USM pointer was provided, the data is not free'd. The SYCL command queue which will be used for SYCL kernels execution. dmhandle - Handle initialized with :ref:`onemkl_sparse_create_dense_matrix`. + Handle initialized with :ref:`onemkl_sparse_init_dense_matrix`. dependencies List of events to depend on before starting asynchronous tasks that access diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/destroy_dense_vector.rst b/source/elements/oneMKL/source/domains/spblas/data_types/release_dense_vector.rst similarity index 86% rename from source/elements/oneMKL/source/domains/spblas/data_types/destroy_dense_vector.rst rename to source/elements/oneMKL/source/domains/spblas/data_types/release_dense_vector.rst index 651fc9f66..73b186048 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/destroy_dense_vector.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/release_dense_vector.rst @@ -2,16 +2,16 @@ .. .. SPDX-License-Identifier: CC-BY-4.0 -.. _onemkl_sparse_destroy_dense_vector: +.. _onemkl_sparse_release_dense_vector: -destroy_dense_vector +release_dense_vector ==================== Destroys a ``dense_vector_handle_t`` object. .. rubric:: Description and Assumptions -The ``oneapi::mkl::sparse::destroy_dense_vector`` function frees the resources +The ``oneapi::mkl::sparse::release_dense_vector`` function frees the resources allocated for the handle. If a buffer was provided, its reference count is decremented. @@ -24,7 +24,7 @@ If a USM pointer was provided, the data is not free'd. namespace oneapi::mkl::sparse { - sycl::event destroy_dense_vector (sycl::queue &queue, + sycl::event release_dense_vector (sycl::queue &queue, oneapi::mkl::sparse::dense_vector_handle_t dvhandle, const std::vector &dependencies = {}); @@ -38,7 +38,7 @@ If a USM pointer was provided, the data is not free'd. The SYCL command queue which will be used for SYCL kernels execution. dvhandle - Handle initialized with :ref:`onemkl_sparse_create_dense_vector`. + Handle initialized with :ref:`onemkl_sparse_init_dense_vector`. dependencies List of events to depend on before starting asynchronous tasks that access diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/destroy_sparse_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/release_sparse_matrix.rst similarity index 84% rename from source/elements/oneMKL/source/domains/spblas/data_types/destroy_sparse_matrix.rst rename to source/elements/oneMKL/source/domains/spblas/data_types/release_sparse_matrix.rst index e1ec6bbfe..d1d549335 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/destroy_sparse_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/release_sparse_matrix.rst @@ -2,16 +2,16 @@ .. .. SPDX-License-Identifier: CC-BY-4.0 -.. _onemkl_sparse_destroy_sparse_matrix: +.. _onemkl_sparse_release_sparse_matrix: -destroy_sparse_matrix +release_sparse_matrix ===================== Destroys a ``matrix_handle_t`` object. .. rubric:: Description and Assumptions -The ``oneapi::mkl::sparse::destroy_sparse_matrix`` function frees the resources +The ``oneapi::mkl::sparse::release_sparse_matrix`` function frees the resources allocated for the handle. If a buffer was provided, its reference count is decremented. @@ -24,7 +24,7 @@ If a USM pointer was provided, the data is not free'd. namespace oneapi::mkl::sparse { - sycl::event destroy_sparse_matrix (sycl::queue &queue, + sycl::event release_sparse_matrix (sycl::queue &queue, oneapi::mkl::sparse::matrix_handle_t smhandle, const std::vector &dependencies = {}); @@ -38,8 +38,8 @@ If a USM pointer was provided, the data is not free'd. The SYCL command queue which will be used for SYCL kernels execution. smhandle - Handle initialized with :ref:`onemkl_sparse_create_csr_matrix` or - :ref:`onemkl_sparse_create_coo_matrix`. + Handle initialized with :ref:`onemkl_sparse_init_csr_matrix` or + :ref:`onemkl_sparse_init_coo_matrix`. dependencies List of events to depend on before starting asynchronous tasks that access diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst index 1b8e1f732..a8a275ed0 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst @@ -16,12 +16,12 @@ The ``oneapi::mkl::sparse::set_coo_matrix_data`` function sets new data to the In the case of buffers, the reference count of the provided buffer is incremented which extends the lifetime of the underlying buffer until the -``smhandle`` is destroyed with ``destroy_sparse_matrix`` or the data is reset with -``set_coo_matrix_data``. +``smhandle`` is destroyed with ``release_sparse_matrix`` or the data is reset +with ``set_coo_matrix_data``. In the case of USM, the object does not take ownership of the data. -Also see :ref:`onemkl_sparse_create_coo_matrix`. +Also see :ref:`onemkl_sparse_init_coo_matrix`. .. _onemkl_sparse_set_coo_matrix_data_buffer: @@ -67,7 +67,7 @@ set_coo_matrix_data (Buffer version) The SYCL command queue which will be used for SYCL kernels execution. smhandle - Handle already initialized with :ref:`onemkl_sparse_create_coo_matrix`. + Handle already initialized with :ref:`onemkl_sparse_init_coo_matrix`. num_rows Number of rows of the provided data ``val``. Must be at least 0. @@ -164,7 +164,7 @@ set_coo_matrix_data (USM version) The SYCL command queue which will be used for SYCL kernels execution. smhandle - Handle already initialized with :ref:`onemkl_sparse_create_coo_matrix`. + Handle already initialized with :ref:`onemkl_sparse_init_coo_matrix`. num_rows Number of rows of the provided data ``val``. Must be at least 0. diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst index 547629e33..a5d103c00 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst @@ -16,12 +16,12 @@ The ``oneapi::mkl::sparse::set_csr_matrix_data`` function sets new data to the In the case of buffers, the reference count of the provided buffer is incremented which extends the lifetime of the underlying buffer until the -``smhandle`` is destroyed with ``destroy_sparse_matrix`` or the data is reset with -``set_csr_matrix_data``. +``smhandle`` is destroyed with ``release_sparse_matrix`` or the data is reset +with ``set_csr_matrix_data``. In the case of USM, the object does not take ownership of the data. -Also see :ref:`onemkl_sparse_create_csr_matrix`. +Also see :ref:`onemkl_sparse_init_csr_matrix`. .. _onemkl_sparse_set_csr_matrix_data_buffer: @@ -67,7 +67,7 @@ set_csr_matrix_data (Buffer version) The SYCL command queue which will be used for SYCL kernels execution. smhandle - Handle already initialized with :ref:`onemkl_sparse_create_csr_matrix`. + Handle already initialized with :ref:`onemkl_sparse_init_csr_matrix`. num_rows Number of rows of the provided data ``val``. Must be at least 0. @@ -163,7 +163,7 @@ set_csr_matrix_data (USM version) The SYCL command queue which will be used for SYCL kernels execution. smhandle - Handle already initialized with :ref:`onemkl_sparse_create_csr_matrix`. + Handle already initialized with :ref:`onemkl_sparse_init_csr_matrix`. num_rows Number of rows of the provided data ``val``. Must be at least 0. diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst index a4beb7ef3..2adbb39f3 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst @@ -16,12 +16,12 @@ The ``oneapi::mkl::sparse::set_dense_matrix_data`` function sets new data to the In the case of buffers, the reference count of the provided buffer is incremented which extends the lifetime of the underlying buffer until the -``dmhandle`` is destroyed with ``destroy_dense_matrix`` or the data is reset +``dmhandle`` is destroyed with ``release_dense_matrix`` or the data is reset with ``set_dense_matrix_data``. In the case of USM, the object does not take ownership of the data. -Also see :ref:`onemkl_sparse_create_dense_matrix`. +Also see :ref:`onemkl_sparse_init_dense_matrix`. .. _onemkl_sparse_set_dense_matrix_data_buffer: @@ -62,7 +62,7 @@ set_dense_matrix_data (Buffer version) The SYCL command queue which will be used for SYCL kernels execution. dmhandle - Handle already initialized with :ref:`onemkl_sparse_create_dense_matrix`. + Handle already initialized with :ref:`onemkl_sparse_init_dense_matrix`. num_rows Number of rows of the provided data ``val``. Must be at least 0. @@ -135,7 +135,7 @@ set_dense_matrix_data (USM version) The SYCL command queue which will be used for SYCL kernels execution. dmhandle - Handle already initialized with :ref:`onemkl_sparse_create_dense_matrix`. + Handle already initialized with :ref:`onemkl_sparse_init_dense_matrix`. num_rows Number of rows of the provided data ``val``. Must be at least 1. diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst index dcdbf1b76..637623c28 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst @@ -16,12 +16,12 @@ The ``oneapi::mkl::sparse::set_dense_vector_data`` function sets new data to the In the case of buffers, the reference count of the provided buffer is incremented which extends the lifetime of the underlying buffer until the -``dvhandle`` is destroyed with ``destroy_dense_vector`` or the data is reset +``dvhandle`` is destroyed with ``release_dense_vector`` or the data is reset with ``set_dense_vector_data``. In the case of USM, the object does not take ownership of the data. -Also see :ref:`onemkl_sparse_create_dense_vector`. +Also see :ref:`onemkl_sparse_init_dense_vector`. .. _onemkl_sparse_set_dense_vector_data_buffer: @@ -59,7 +59,7 @@ set_dense_vector_data (Buffer version) The SYCL command queue which will be used for SYCL kernels execution. dvhandle - Handle already initialized with :ref:`onemkl_sparse_create_dense_vector`. + Handle already initialized with :ref:`onemkl_sparse_init_dense_vector`. size Number of elements of the provided data ``val``. Must be at least 0. @@ -117,7 +117,7 @@ set_dense_vector_data (USM version) The SYCL command queue which will be used for SYCL kernels execution. dvhandle - Handle already initialized with :ref:`onemkl_sparse_create_dense_vector`. + Handle already initialized with :ref:`onemkl_sparse_init_dense_vector`. size Number of elements of the provided data ``val``. Must be at least 1. From ed396953de2b14170c17213b6f6b020af01b3d9c Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Sat, 6 Apr 2024 18:33:48 +0100 Subject: [PATCH 37/52] More rewording regarding nnz --- .../spblas/data_types/init_coo_matrix.rst | 25 ++++++++++--------- .../spblas/data_types/init_csr_matrix.rst | 25 ++++++++++--------- .../spblas/data_types/set_coo_matrix_data.rst | 25 ++++++++++--------- .../spblas/data_types/set_csr_matrix_data.rst | 25 ++++++++++--------- 4 files changed, 52 insertions(+), 48 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/init_coo_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/init_coo_matrix.rst index 4ebd1220f..060a6a120 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/init_coo_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/init_coo_matrix.rst @@ -85,8 +85,8 @@ init_coo_matrix (Buffer version) Number of columns of the provided data ``val``. Must be at least 0. nnz - Number of non-zero entries in the matrix (which may include explicit - zeros). Must be at least 0. + The number of explicit entries, also known as Number of Non-Zero elements. + Must be at least 0. index Indicates how input arrays are indexed. The possible options are described @@ -103,9 +103,10 @@ init_coo_matrix (Buffer version) detailed description of ``col_ind``. val - Buffer of length at least ``nnz`` containing non-zero elements (and - possibly explicit zeros) of the input matrix. Refer to - :ref:`onemkl_sparse_coo` format for detailed description of ``val``. + Buffer of length at least ``nnz``. Contains the data of the input matrix + which is not implicitly zero. The remaining input values are implicit + zeros. Refer to :ref:`onemkl_sparse_coo` format for detailed description + of ``val``. .. container:: section @@ -190,8 +191,8 @@ init_coo_matrix (USM version) Number of columns of the provided data ``val``. Must be at least 0. nnz - Number of non-zero entries in the matrix (which may include explicit - zeros). Must be at least 0. + The number of explicit entries, also known as Number of Non-Zero elements. + Must be at least 0. index Indicates how input arrays are indexed. The possible options are described @@ -210,11 +211,11 @@ init_coo_matrix (USM version) device. val - USM pointer of length at least ``nnz`` containing non-zero elements (and - possibly explicit zeros) of the input matrix. Refer to - :ref:`onemkl_sparse_coo` format for detailed description of ``val``. The - data must be accessible on the device. Using a USM pointer with a smaller - allocated memory size is undefined behavior. + USM pointer of length at least ``nnz``. Contains the data of the input + matrix which is not implicitly zero. The remaining input values are + implicit zeros. Refer to :ref:`onemkl_sparse_coo` format for detailed + description of ``val``. The data must be accessible on the device. Using a + USM pointer with a smaller allocated memory size is undefined behavior. .. container:: section diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/init_csr_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/init_csr_matrix.rst index a1c37b6b4..faf7e493b 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/init_csr_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/init_csr_matrix.rst @@ -86,8 +86,8 @@ init_csr_matrix (Buffer version) Number of columns of the provided data ``val``. Must be at least 0. nnz - Number of non-zero entries in the matrix (which may include explicit - zeros). Must be at least 0. + The number of explicit entries, also known as Number of Non-Zero elements. + Must be at least 0. index Indicates how input arrays are indexed. The possible options are described @@ -103,9 +103,10 @@ init_csr_matrix (Buffer version) detailed description of ``col_ind``. val - Buffer of length at least ``nnz`` containing non-zero elements (and - possibly explicit zeros) of the input matrix. Refer to - :ref:`onemkl_sparse_csr` format for detailed description of ``val``. + Buffer of length at least ``nnz``. Contains the data of the input matrix + which is not implicitly zero. The remaining input values are implicit + zeros. Refer to :ref:`onemkl_sparse_csr` format for detailed description + of ``val``. .. container:: section @@ -190,8 +191,8 @@ init_csr_matrix (USM version) Number of columns of the provided data ``val``. Must be at least 0. nnz - Number of non-zero entries in the matrix (which may include explicit - zeros). Must be at least 0. + The number of explicit entries, also known as Number of Non-Zero elements. + Must be at least 0. index Indicates how input arrays are indexed. The possible options are described @@ -209,11 +210,11 @@ init_csr_matrix (USM version) device. val - USM pointer of length at least ``nnz`` containing non-zero elements (and - possibly explicit zeros) of the input matrix. Refer to - :ref:`onemkl_sparse_csr` format for detailed description of ``val``. The - data must be accessible on the device. Using a USM pointer with a smaller - allocated memory size is undefined behavior. + USM pointer of length at least ``nnz``. Contains the data of the input + matrix which is not implicitly zero. The remaining input values are + implicit zeros. Refer to :ref:`onemkl_sparse_csr` format for detailed + description of ``val``. The data must be accessible on the device. Using a + USM pointer with a smaller allocated memory size is undefined behavior. .. container:: section diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst index a8a275ed0..4685b6f06 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst @@ -76,8 +76,8 @@ set_coo_matrix_data (Buffer version) Number of columns of the provided data ``val``. Must be at least 0. nnz - Number of non-zero entries in the matrix (which may include explicit - zeros). Must be at least 0. + The number of explicit entries, also known as Number of Non-Zero elements. + Must be at least 0. index Indicates how input arrays are indexed. The possible options are described @@ -94,9 +94,10 @@ set_coo_matrix_data (Buffer version) detailed description of ``col_ind``. val - Buffer of length at least ``nnz`` containing non-zero elements (and - possibly explicit zeros) of the input matrix. Refer to - :ref:`onemkl_sparse_coo` format for detailed description of ``val``. + Buffer of length at least ``nnz``. Contains the data of the input matrix + which is not implicitly zero. The remaining input values are implicit + zeros. Refer to :ref:`onemkl_sparse_coo` format for detailed description + of ``val``. .. container:: section @@ -173,8 +174,8 @@ set_coo_matrix_data (USM version) Number of columns of the provided data ``val``. Must be at least 0. nnz - Number of non-zero entries in the matrix (which may include explicit - zeros). Must be at least 0. + The number of explicit entries, also known as Number of Non-Zero elements. + Must be at least 0. index Indicates how input arrays are indexed. The possible options are described @@ -193,11 +194,11 @@ set_coo_matrix_data (USM version) device. val - USM pointer of length at least ``nnz`` containing non-zero elements (and - possibly explicit zeros) of the input matrix. Refer to - :ref:`onemkl_sparse_coo` format for detailed description of ``val``. The - data must be accessible on the device. Using a USM pointer with a smaller - allocated memory size is undefined behavior. + USM pointer of length at least ``nnz``. Contains the data of the input + matrix which is not implicitly zero. The remaining input values are + implicit zeros. Refer to :ref:`onemkl_sparse_coo` format for detailed + description of ``val``. The data must be accessible on the device. Using a + USM pointer with a smaller allocated memory size is undefined behavior. .. container:: section diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst index a5d103c00..1db09fc0d 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst @@ -76,8 +76,8 @@ set_csr_matrix_data (Buffer version) Number of columns of the provided data ``val``. Must be at least 0. nnz - Number of non-zero entries in the matrix (which may include explicit - zeros). Must be at least 0. + The number of explicit entries, also known as Number of Non-Zero elements. + Must be at least 0. index Indicates how input arrays are indexed. The possible options are described @@ -93,9 +93,10 @@ set_csr_matrix_data (Buffer version) detailed description of ``col_ind``. val - Buffer of length at least ``nnz`` containing non-zero elements (and - possibly explicit zeros) of the input matrix. Refer to - :ref:`onemkl_sparse_csr` format for detailed description of ``val``. + Buffer of length at least ``nnz``. Contains the data of the input matrix + which is not implicitly zero. The remaining input values are implicit + zeros. Refer to :ref:`onemkl_sparse_csr` format for detailed description + of ``val``. .. container:: section @@ -172,8 +173,8 @@ set_csr_matrix_data (USM version) Number of columns of the provided data ``val``. Must be at least 0. nnz - Number of non-zero entries in the matrix (which may include explicit - zeros). Must be at least 0. + The number of explicit entries, also known as Number of Non-Zero elements. + Must be at least 0. index Indicates how input arrays are indexed. The possible options are described @@ -191,11 +192,11 @@ set_csr_matrix_data (USM version) device. val - USM pointer of length at least ``nnz`` containing non-zero elements (and - possibly explicit zeros) of the input matrix. Refer to - :ref:`onemkl_sparse_csr` format for detailed description of ``val``. The - data must be accessible on the device. Using a USM pointer with a smaller - allocated memory size is undefined behavior. + USM pointer of length at least ``nnz``. Contains the data of the input + matrix which is not implicitly zero. The remaining input values are + implicit zeros. Refer to :ref:`onemkl_sparse_csr` format for detailed + description of ``val``. The data must be accessible on the device. Using a + USM pointer with a smaller allocated memory size is undefined behavior. .. container:: section From 32e43ffa1cf49ddf2050eb807c15043995ea1ef8 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Sat, 6 Apr 2024 21:32:26 +0100 Subject: [PATCH 38/52] Make alpha and beta const --- .../source/domains/spblas/operations/spmm.rst | 16 ++++++++-------- .../source/domains/spblas/operations/spmv.rst | 16 ++++++++-------- .../source/domains/spblas/operations/spsv.rst | 8 ++++---- 3 files changed, 20 insertions(+), 20 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst index f7e0b5549..38c1c39f3 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst @@ -208,11 +208,11 @@ spmm sycl::queue &queue, oneapi::mkl::transpose opA, oneapi::mkl::transpose opB, - void* alpha, + const void* alpha, oneapi::mkl::sparse::matrix_view A_view, oneapi::mkl::sparse::matrix_handle_t A_handle, oneapi::mkl::sparse::dense_matrix_handle_t B_handle, - void* beta, + const void* beta, oneapi::mkl::sparse::dense_matrix_handle_t C_handle, oneapi::mkl::sparse::spmm_alg alg, oneapi::mkl::sparse::spmm_descr_t spmm_descr, @@ -222,11 +222,11 @@ spmm sycl::queue &queue, oneapi::mkl::transpose opA, oneapi::mkl::transpose opB, - void* alpha, + const void* alpha, oneapi::mkl::sparse::matrix_view A_view, oneapi::mkl::sparse::matrix_handle_t A_handle, oneapi::mkl::sparse::dense_matrix_handle_t B_handle, - void* beta, + const void* beta, oneapi::mkl::sparse::dense_matrix_handle_t C_handle, oneapi::mkl::sparse::spmm_alg alg, oneapi::mkl::sparse::spmm_descr_t spmm_descr, @@ -236,11 +236,11 @@ spmm sycl::queue &queue, oneapi::mkl::transpose opA, oneapi::mkl::transpose opB, - void* alpha, + const void* alpha, oneapi::mkl::sparse::matrix_view A_view, oneapi::mkl::sparse::matrix_handle_t A_handle, oneapi::mkl::sparse::dense_matrix_handle_t B_handle, - void* beta, + const void* beta, oneapi::mkl::sparse::dense_matrix_handle_t C_handle, oneapi::mkl::sparse::spmm_alg alg, oneapi::mkl::sparse::spmm_descr_t spmm_descr, @@ -251,11 +251,11 @@ spmm sycl::queue &queue, oneapi::mkl::transpose opA, oneapi::mkl::transpose opB, - void* alpha, + const void* alpha, oneapi::mkl::sparse::matrix_view A_view, oneapi::mkl::sparse::matrix_handle_t A_handle, oneapi::mkl::sparse::dense_matrix_handle_t B_handle, - void* beta, + const void* beta, oneapi::mkl::sparse::dense_matrix_handle_t C_handle, oneapi::mkl::sparse::spmm_alg alg, oneapi::mkl::sparse::spmm_descr_t spmm_descr, diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst index 57b542bf0..69bf7b024 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst @@ -205,11 +205,11 @@ spmv void spmv_buffer_size( sycl::queue &queue, oneapi::mkl::transpose opA, - void* alpha, + const void* alpha, oneapi::mkl::sparse::matrix_view A_view, oneapi::mkl::sparse::matrix_handle_t A_handle, oneapi::mkl::sparse::dense_vector_handle_t x_handle, - void* beta, + const void* beta, oneapi::mkl::sparse::dense_vector_handle_t y_handle, oneapi::mkl::sparse::spmv_alg alg, oneapi::mkl::sparse::spmv_descr_t spmv_descr, @@ -218,11 +218,11 @@ spmv void spmv_optimize( sycl::queue &queue, oneapi::mkl::transpose opA, - void* alpha, + const void* alpha, oneapi::mkl::sparse::matrix_view A_view, oneapi::mkl::sparse::matrix_handle_t A_handle, oneapi::mkl::sparse::dense_vector_handle_t x_handle, - void* beta, + const void* beta, oneapi::mkl::sparse::dense_vector_handle_t y_handle, oneapi::mkl::sparse::spmv_alg alg, oneapi::mkl::sparse::spmv_descr_t spmv_descr, @@ -231,11 +231,11 @@ spmv sycl::event spmv_optimize( sycl::queue &queue, oneapi::mkl::transpose opA, - void* alpha, + const void* alpha, oneapi::mkl::sparse::matrix_view A_view, oneapi::mkl::sparse::matrix_handle_t A_handle, oneapi::mkl::sparse::dense_vector_handle_t x_handle, - void* beta, + const void* beta, oneapi::mkl::sparse::dense_vector_handle_t y_handle, oneapi::mkl::sparse::spmv_alg alg, oneapi::mkl::sparse::spmv_descr_t spmv_descr, @@ -245,11 +245,11 @@ spmv sycl::event spmv( sycl::queue &queue, oneapi::mkl::transpose opA, - void* alpha, + const void* alpha, oneapi::mkl::sparse::matrix_view A_view, oneapi::mkl::sparse::matrix_handle_t A_handle, oneapi::mkl::sparse::dense_vector_handle_t x_handle, - void* beta, + const void* beta, oneapi::mkl::sparse::dense_vector_handle_t y_handle, oneapi::mkl::sparse::spmv_alg alg, oneapi::mkl::sparse::spmv_descr_t spmv_descr, diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst index a25f7fdc4..1ba5357c4 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst @@ -200,7 +200,7 @@ spsv void spsv_buffer_size( sycl::queue &queue, oneapi::mkl::transpose opA, - void* alpha, + const void* alpha, oneapi::mkl::sparse::matrix_view A_view, oneapi::mkl::sparse::matrix_handle_t A_handle, oneapi::mkl::sparse::dense_vector_handle_t x_handle, @@ -212,7 +212,7 @@ spsv void spsv_optimize( sycl::queue &queue, oneapi::mkl::transpose opA, - void* alpha, + const void* alpha, oneapi::mkl::sparse::matrix_view A_view, oneapi::mkl::sparse::matrix_handle_t A_handle, oneapi::mkl::sparse::dense_vector_handle_t x_handle, @@ -224,7 +224,7 @@ spsv sycl::event spsv_optimize( sycl::queue &queue, oneapi::mkl::transpose opA, - void* alpha, + const void* alpha, oneapi::mkl::sparse::matrix_view A_view, oneapi::mkl::sparse::matrix_handle_t A_handle, oneapi::mkl::sparse::dense_vector_handle_t x_handle, @@ -237,7 +237,7 @@ spsv sycl::event spsv( sycl::queue &queue, oneapi::mkl::transpose opA, - void* alpha, + const void* alpha, oneapi::mkl::sparse::matrix_view A_view, oneapi::mkl::sparse::matrix_handle_t A_handle, oneapi::mkl::sparse::dense_vector_handle_t x_handle, From 15ec0e501cb06a4a957376dd9525cb1babe8e644 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Sun, 7 Apr 2024 12:18:32 +0100 Subject: [PATCH 39/52] Clarify that optimize functions can reset the descriptor's data --- .../oneMKL/source/domains/spblas/operations/spmm.rst | 6 ++++-- .../oneMKL/source/domains/spblas/operations/spmv.rst | 6 ++++-- .../oneMKL/source/domains/spblas/operations/spsv.rst | 6 ++++-- 3 files changed, 12 insertions(+), 6 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst index 38c1c39f3..002f78c0f 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst @@ -267,8 +267,10 @@ spmm .. rubric:: Notes - - ``spmm_buffer_size`` and ``spmm_optimize`` must be called at least once before ``spmm`` - with the same arguments. ``spmm`` can then be called multiple times. + - ``spmm_buffer_size`` and ``spmm_optimize`` must be called at least once + before ``spmm`` with the same arguments. ``spmm`` can then be called + multiple times. Calling ``spmm_optimize`` on the same descriptor can reset + some of the descriptor's data such as the ``workspace``. - The data of the handles can be reset-ed before each call to ``spmm``. - ``spmm_optimize`` and ``spmm`` are asynchronous. - The algorithm defaults to ``spmm_alg::default_alg`` if a backend does not diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst index 69bf7b024..b647cfe7e 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst @@ -261,8 +261,10 @@ spmv .. rubric:: Notes - - ``spmv_buffer_size`` and ``spmv_optimize`` must be called at least once before ``spmv`` - with the same arguments. ``spmv`` can then be called multiple times. + - ``spmv_buffer_size`` and ``spmv_optimize`` must be called at least once + before ``spmv`` with the same arguments. ``spmv`` can then be called + multiple times. Calling ``spmv_optimize`` on the same descriptor can reset + some of the descriptor's data such as the ``workspace``. - The data of the handles can be reset-ed before each call to ``spmv``. - ``spmv_optimize`` and ``spmv`` are asynchronous. - The algorithm defaults to ``spmv_alg::default_alg`` if a backend does not diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst index 1ba5357c4..2271b07c1 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst @@ -252,8 +252,10 @@ spsv .. rubric:: 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. + - ``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``. - The data of the handles can be reset-ed before each call to ``spsv``. - ``spsv_optimize`` and ``spsv`` are asynchronous. - The algorithm defaults to ``spsv_alg::default_alg`` if a backend does not From 16ed109830536667b3939cbf6991f6cd726ed322 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Thu, 11 Apr 2024 11:30:54 +0100 Subject: [PATCH 40/52] Remove references from buffers --- .../source/domains/spblas/data_types/init_coo_matrix.rst | 6 +++--- .../source/domains/spblas/data_types/init_csr_matrix.rst | 6 +++--- .../source/domains/spblas/data_types/init_dense_matrix.rst | 2 +- .../source/domains/spblas/data_types/init_dense_vector.rst | 2 +- .../domains/spblas/data_types/set_coo_matrix_data.rst | 6 +++--- .../domains/spblas/data_types/set_csr_matrix_data.rst | 6 +++--- .../domains/spblas/data_types/set_dense_matrix_data.rst | 2 +- .../domains/spblas/data_types/set_dense_vector_data.rst | 2 +- 8 files changed, 16 insertions(+), 16 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/init_coo_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/init_coo_matrix.rst index 060a6a120..7f955e388 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/init_coo_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/init_coo_matrix.rst @@ -51,9 +51,9 @@ init_coo_matrix (Buffer version) std::int64_t num_cols, std::int64_t nnz, index_base index, - sycl::buffer &row_ind, - sycl::buffer &col_ind, - sycl::buffer &val); + sycl::buffer row_ind, + sycl::buffer col_ind, + sycl::buffer val); } diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/init_csr_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/init_csr_matrix.rst index faf7e493b..cf8a14eb2 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/init_csr_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/init_csr_matrix.rst @@ -52,9 +52,9 @@ init_csr_matrix (Buffer version) std::int64_t num_cols, std::int64_t nnz, index_base index, - sycl::buffer &row_ptr, - sycl::buffer &col_ind, - sycl::buffer &val); + sycl::buffer row_ptr, + sycl::buffer col_ind, + sycl::buffer val); } diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/init_dense_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/init_dense_matrix.rst index ebcb4d553..15c37b498 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/init_dense_matrix.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/init_dense_matrix.rst @@ -41,7 +41,7 @@ init_dense_matrix (Buffer version) std::int64_t num_cols, std::int64_t ld, layout dense_layout, - sycl::buffer &val); + sycl::buffer val); } diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/init_dense_vector.rst b/source/elements/oneMKL/source/domains/spblas/data_types/init_dense_vector.rst index 2fe1f6a7e..50b6de6c7 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/init_dense_vector.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/init_dense_vector.rst @@ -38,7 +38,7 @@ init_dense_vector (Buffer version) void init_dense_vector (sycl::queue &queue, oneapi::mkl::sparse::dense_vector_handle_t *p_dvhandle, std::int64_t size, - sycl::buffer &val); + sycl::buffer val); } diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst index 4685b6f06..a6dba2712 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst @@ -41,9 +41,9 @@ set_coo_matrix_data (Buffer version) std::int64_t num_cols, std::int64_t nnz, index_base index, - sycl::buffer &row_ind, - sycl::buffer &col_ind, - sycl::buffer &val); + sycl::buffer row_ind, + sycl::buffer col_ind, + sycl::buffer val); } diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst index 1db09fc0d..3a28785d0 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst @@ -41,9 +41,9 @@ set_csr_matrix_data (Buffer version) std::int64_t num_cols, std::int64_t nnz, index_base index, - sycl::buffer &row_ptr, - sycl::buffer &col_ind, - sycl::buffer &val); + sycl::buffer row_ptr, + sycl::buffer col_ind, + sycl::buffer val); } diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst index 2adbb39f3..c75a80e74 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst @@ -41,7 +41,7 @@ set_dense_matrix_data (Buffer version) std::int64_t num_cols, std::int64_t ld, layout dense_layout, - sycl::buffer &val); + sycl::buffer val); } diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst index 637623c28..844e73bf7 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst @@ -38,7 +38,7 @@ set_dense_vector_data (Buffer version) void set_dense_vector_data (sycl::queue &queue, oneapi::mkl::sparse::dense_vector_handle_t dvhandle, std::int64_t size, - sycl::buffer &val); + sycl::buffer val); } From 1060c7a104d8390b2335ce7b82a1a1f3cdd035b5 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Fri, 26 Apr 2024 16:38:12 +0100 Subject: [PATCH 41/52] Clarify container types must be consistent --- .../oneMKL/source/domains/spblas/operations/spmm.rst | 10 ++++++---- .../oneMKL/source/domains/spblas/operations/spmv.rst | 10 ++++++---- .../oneMKL/source/domains/spblas/operations/spsv.rst | 6 ++++-- 3 files changed, 16 insertions(+), 10 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst index 002f78c0f..8893d5f13 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst @@ -275,6 +275,8 @@ spmm - ``spmm_optimize`` and ``spmm`` are asynchronous. - The algorithm defaults to ``spmm_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. .. rubric:: Input Parameters @@ -291,8 +293,8 @@ spmm alpha Host or USM pointer representing :math:`\alpha`. The USM allocation can be - on the host or device. Must be of the same type than the handles' data - type. + on the host or device. Must be a host pointer if SYCL buffers are used. + Must be of the same type than the handles' data type. A_view Specifies which part of the handle should be read as described by @@ -306,8 +308,8 @@ spmm beta Host or USM pointer representing :math:`\beta`. The USM allocation can be - on the host or device. Must be of the same type than the handles' data - type. + on the host or device. Must be a host pointer if SYCL buffers are used. + Must be of the same type than the handles' data type. C_handle Dense matrix handle object representing :math:`C`. diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst index b647cfe7e..b656e4ab6 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst @@ -269,6 +269,8 @@ spmv - ``spmv_optimize`` and ``spmv`` are asynchronous. - The algorithm defaults to ``spmv_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. .. rubric:: Input Parameters @@ -281,8 +283,8 @@ spmv alpha Host or USM pointer representing :math:`\alpha`. The USM allocation can be - on the host or device. Must be of the same type than the handles' data - type. + on the host or device. Must be a host pointer if SYCL buffers are used. + Must be of the same type than the handles' data type. A_view Specifies which part of the handle should be read as described by @@ -296,8 +298,8 @@ spmv beta Host or USM pointer representing :math:`\beta`. The USM allocation can be - on the host or device. Must be of the same type than the handles' data - type. + on the host or device. Must be a host pointer if SYCL buffers are used. + Must be of the same type than the handles' data type. y_handle Dense vector handle object representing :math:`y`. diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst index 2271b07c1..72c83b56c 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst @@ -260,6 +260,8 @@ spsv - ``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. .. rubric:: Input Parameters @@ -272,8 +274,8 @@ spsv alpha Host or USM pointer representing :math:`\alpha`. The USM allocation can be - on the host or device. Must be of the same type than the handles' data - type. + on the host or device. Must be a host pointer if SYCL buffers are used. + Must be of the same type than the handles' data type. A_view Specifies which part of the handle should be read as described by From 51e406894e237358e9609a226c0cff1f275e0afe Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Thu, 2 May 2024 17:55:02 +0200 Subject: [PATCH 42/52] Clarify restrictions to reset handles' data --- .../oneMKL/source/domains/spblas/operations/spmm.rst | 5 ++++- .../oneMKL/source/domains/spblas/operations/spmv.rst | 5 ++++- .../oneMKL/source/domains/spblas/operations/spsv.rst | 2 +- 3 files changed, 9 insertions(+), 3 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst index 8893d5f13..7b479719e 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst @@ -271,7 +271,10 @@ spmm before ``spmm`` with the same arguments. ``spmm`` can then be called multiple times. Calling ``spmm_optimize`` on the same descriptor can reset some of the descriptor's data such as the ``workspace``. - - The data of the handles can be reset-ed before each call to ``spmm``. + - The data of the sparse handle ``A_handle`` can be reset-ed before each call + to ``spmm`` as long as the sparisty pattern stays the same. The data of the + dense handles ``B_handle`` and ``C_handle`` can be reset-ed before each + call to ``spmm``. - ``spmm_optimize`` and ``spmm`` are asynchronous. - The algorithm defaults to ``spmm_alg::default_alg`` if a backend does not support the provided algorithm. diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst index b656e4ab6..e5ca4b69e 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst @@ -265,7 +265,10 @@ spmv before ``spmv`` with the same arguments. ``spmv`` can then be called multiple times. Calling ``spmv_optimize`` on the same descriptor can reset some of the descriptor's data such as the ``workspace``. - - The data of the handles can be reset-ed before each call to ``spmv``. + - The data of the sparse handle ``A_handle`` can be reset-ed before each call + to ``spmv`` as long as the sparisty pattern stays the same. The data of the + dense handles ``x_handle`` and ``y_handle`` can be reset-ed before each + call to ``spmv``. - ``spmv_optimize`` and ``spmv`` are asynchronous. - The algorithm defaults to ``spmv_alg::default_alg`` if a backend does not support the provided algorithm. diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst index 72c83b56c..6969f979a 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst @@ -256,7 +256,7 @@ spsv 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``. - - The data of the handles can be reset-ed before each call to ``spsv``. + - The data of the dense handle ``x_handle`` can be reset-ed before each call to ``spsv``. - ``spsv_optimize`` and ``spsv`` are asynchronous. - The algorithm defaults to ``spsv_alg::default_alg`` if a backend does not support the provided algorithm. From ebc779ced269cf6d6b429c1897b79d071fe79c06 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Fri, 3 May 2024 18:14:21 +0200 Subject: [PATCH 43/52] Add comment on COO performance --- .../source/domains/spblas/data_types/format-descriptions.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/format-descriptions.rst b/source/elements/oneMKL/source/domains/spblas/data_types/format-descriptions.rst index 63faeb15b..33ab4b153 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/format-descriptions.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/format-descriptions.rst @@ -26,7 +26,10 @@ entries are implicitly zeros. arrays, ``row_ind``, ``col_ind`` and ``val``, and an ``index`` parameter. The ``i``-th defined element in the sparse matrix is represented by its row index, column index, and value, that is, (``row_ind[i]``, ``col_ind[i]``, - ``val[i]``). The entries need not be in a sorted order. + ``val[i]``). The entries need not be in a sorted order, though performance of + Sparse BLAS operations may be improved if they are sorted in some logical + way, for instance by row index and then column index subordinate to each row + set. .. container:: tablenoborder From 7247b6d78a98ffe39c269e11bf15aaeea18076f8 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Fri, 3 May 2024 18:30:42 +0200 Subject: [PATCH 44/52] Clarify matrix_properties are hints --- .../domains/spblas/data_types/set_matrix_properties.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_properties.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_properties.rst index 73d654e0f..9682aec55 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_properties.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_properties.rst @@ -25,8 +25,8 @@ Matrix properties Matrix properties are optional and "strong" guarantees. Unlike :ref:`onemkl_sparse_matrix_view`, the user must ensure that the handle's data - holds all the given properties. A property can be set to optimize some - operations. + holds all the given properties. A property can be set as a hint for backends + to optimize some operations. .. list-table:: :header-rows: 1 From 38dbaef53b9e1ba06dc34ab54727abbc8bf873ef Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Fri, 3 May 2024 18:33:27 +0200 Subject: [PATCH 45/52] Fix typos --- .../elements/oneMKL/source/domains/spblas/operations/spmm.rst | 2 +- .../elements/oneMKL/source/domains/spblas/operations/spmv.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst index 7b479719e..715ab5fdf 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst @@ -272,7 +272,7 @@ spmm multiple times. Calling ``spmm_optimize`` on the same descriptor can reset some of the descriptor's data such as the ``workspace``. - The data of the sparse handle ``A_handle`` can be reset-ed before each call - to ``spmm`` as long as the sparisty pattern stays the same. The data of the + to ``spmm`` as long as the sparsity pattern stays the same. The data of the dense handles ``B_handle`` and ``C_handle`` can be reset-ed before each call to ``spmm``. - ``spmm_optimize`` and ``spmm`` are asynchronous. diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst index e5ca4b69e..ec701b8a4 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst @@ -266,7 +266,7 @@ spmv multiple times. Calling ``spmv_optimize`` on the same descriptor can reset some of the descriptor's data such as the ``workspace``. - The data of the sparse handle ``A_handle`` can be reset-ed before each call - to ``spmv`` as long as the sparisty pattern stays the same. The data of the + to ``spmv`` as long as the sparsity pattern stays the same. The data of the dense handles ``x_handle`` and ``y_handle`` can be reset-ed before each call to ``spmv``. - ``spmv_optimize`` and ``spmv`` are asynchronous. From ac1b22388b3615ed559f753105e395a937f2033b Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Fri, 3 May 2024 18:54:31 +0200 Subject: [PATCH 46/52] Add note on operations' descriptor --- .../oneMKL/source/domains/sparse_linear_algebra.inc.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/elements/oneMKL/source/domains/sparse_linear_algebra.inc.rst b/source/elements/oneMKL/source/domains/sparse_linear_algebra.inc.rst index dbb22c377..b48583bd7 100644 --- a/source/elements/oneMKL/source/domains/sparse_linear_algebra.inc.rst +++ b/source/elements/oneMKL/source/domains/sparse_linear_algebra.inc.rst @@ -22,7 +22,8 @@ Sparse Linear Algebra structure changes to enable a more optimized algorithm. User-provided matrix data remain unmodified if such optimizations are made. In the execution stage, multiple routine calls can take advantage of the optimization stage - data in order to improve performance. + data in order to improve performance. Each operation has a descriptor type + that is used to carry information across the different stages. .. toctree:: :hidden: From 1292ad64662bdc650804e5d04b2bba512895c7e7 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Mon, 6 May 2024 11:18:34 +0200 Subject: [PATCH 47/52] Revert to set_matrix_property --- .../spblas/data_types/data_handles.rst | 4 +- ...properties.rst => set_matrix_property.rst} | 38 +++++++++---------- 2 files changed, 20 insertions(+), 22 deletions(-) rename source/elements/oneMKL/source/domains/spblas/data_types/{set_matrix_properties.rst => set_matrix_property.rst} (68%) diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/data_handles.rst b/source/elements/oneMKL/source/domains/spblas/data_types/data_handles.rst index 0e0084cfb..dfcf92212 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/data_handles.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/data_handles.rst @@ -97,7 +97,7 @@ Sparse matrix handle - :ref:`onemkl_sparse_init_csr_matrix` - :ref:`onemkl_sparse_set_coo_matrix_data` - :ref:`onemkl_sparse_set_csr_matrix_data` - - :ref:`onemkl_sparse_set_matrix_properties` + - :ref:`onemkl_sparse_set_matrix_property` - :ref:`onemkl_sparse_release_sparse_matrix` See a description of the supported :ref:`sparse formats`. @@ -116,7 +116,7 @@ Sparse matrix handle set_dense_matrix_data set_coo_matrix_data set_csr_matrix_data - set_matrix_properties + set_matrix_property format-descriptions **Parent topic:** :ref:`onemkl_spblas` diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_properties.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_property.rst similarity index 68% rename from source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_properties.rst rename to source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_property.rst index 9682aec55..a4f97295e 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_properties.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_property.rst @@ -2,10 +2,10 @@ .. .. SPDX-License-Identifier: CC-BY-4.0 -.. _onemkl_sparse_set_matrix_properties: +.. _onemkl_sparse_set_matrix_property: -set_matrix_properties -===================== +set_matrix_property +=================== Matrix properties ----------------- @@ -16,9 +16,9 @@ Matrix properties namespace oneapi::mkl::sparse { - enum matrix_property : std::int32_t { - symmetric = 1 << 0, - sorted = 1 << 1, + enum class matrix_property { + symmetric, + sorted, }; } @@ -26,7 +26,7 @@ Matrix properties Matrix properties are optional and "strong" guarantees. Unlike :ref:`onemkl_sparse_matrix_view`, the user must ensure that the handle's data holds all the given properties. A property can be set as a hint for backends - to optimize some operations. + to optimize some operations. Multiple properties can be set to the same handle. .. list-table:: :header-rows: 1 @@ -46,14 +46,14 @@ Matrix properties | For COO this guarantees that that the row indices are sorted in ascending order. -set_matrix_properties ---------------------- +set_matrix_property +------------------- -Set properties to a ``matrix_handle_t`` object. +Set a property to a ``matrix_handle_t`` object. .. rubric:: Description and Assumptions -The ``oneapi::mkl::sparse::set_matrix_properties`` function sets properties to a +The ``oneapi::mkl::sparse::set_matrix_property`` function sets a property to a matrix handle. .. rubric:: Syntax @@ -62,9 +62,9 @@ matrix handle. namespace oneapi::mkl::sparse { - bool set_matrix_properties (sycl::queue &queue, - oneapi::mkl::sparse::matrix_handle_t smhandle, - std::int32_t properties_mask); + bool set_matrix_property (sycl::queue &queue, + oneapi::mkl::sparse::matrix_handle_t smhandle, + matrix_property property); } @@ -78,17 +78,15 @@ matrix handle. smhandle Initialized sparse matrix handle. - properties_mask - Matrix properties to set. The mask must be composed of one or multiple - values from ``oneapi::mkl::sparse::matrix_property`` combined with the - bitwise-or operator ``|``. Properties can be reset with a mask of 0. + property + Matrix property to set. .. container:: section .. rubric:: Return Values - Return whether the properties were set to the backend's handle. A backend may - not have equivalent properties. + Return whether the property was set to the backend's handle. A backend may + not have an equivalent property. .. container:: section From e279fa305787b4ab268c02cdcd8c4d179af086b3 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Mon, 6 May 2024 22:06:56 +0200 Subject: [PATCH 48/52] Specify that dependencies and events may be unused for buffers --- .../elements/oneMKL/source/domains/spblas/operations/spmm.rst | 4 ++-- .../elements/oneMKL/source/domains/spblas/operations/spmv.rst | 4 ++-- .../elements/oneMKL/source/domains/spblas/operations/spsv.rst | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst index 715ab5fdf..1cc1e8506 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst @@ -338,7 +338,7 @@ spmm dependencies List of events to depend on before starting asynchronous tasks that access - data on the device. Defaults to no dependencies. + data on the device. Ignored if buffers are used. Defaults to no dependencies. .. container:: section @@ -357,7 +357,7 @@ spmm .. rubric:: Return Values Output event that can be waited upon or added as a dependency for the - completion of the function. + completion of the function. May be an empty event if buffers are used. .. container:: section diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst index ec701b8a4..ce743ba8d 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst @@ -328,7 +328,7 @@ spmv dependencies List of events to depend on before starting asynchronous tasks that access - data on the device. Defaults to no dependencies. + data on the device. Ignored if buffers are used. Defaults to no dependencies. .. container:: section @@ -347,7 +347,7 @@ spmv .. rubric:: Return Values Output event that can be waited upon or added as a dependency for the - completion of the function. + completion of the function. May be an empty event if buffers are used. .. container:: section diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst index 6969f979a..c57977219 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst @@ -312,7 +312,7 @@ spsv dependencies List of events to depend on before starting asynchronous tasks that access - data on the device. Defaults to no dependencies. + data on the device. Ignored if buffers are used. Defaults to no dependencies. .. container:: section @@ -331,7 +331,7 @@ spsv .. rubric:: Return Values Output event that can be waited upon or added as a dependency for the - completion of the function. + completion of the function. May be an empty event if buffers are used. .. container:: section From 669a4e7a58796672124662b3010e62ea1e3e5c22 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Tue, 7 May 2024 12:17:08 +0200 Subject: [PATCH 49/52] Clarify sorted property for COO format --- .../source/domains/spblas/data_types/set_matrix_property.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_property.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_property.rst index a4f97295e..6c5a94831 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_property.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_property.rst @@ -43,8 +43,8 @@ Matrix properties property. | For CSR this guarantees that the column indices are sorted in ascending order for a given row. - | For COO this guarantees that that the row indices are sorted in - ascending order. + | For COO this guarantees that the indices are sorted by row then by + column in ascending order. set_matrix_property ------------------- From 8f94f4dfbbddeb4880b04e83cce6470043218c74 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Tue, 7 May 2024 12:21:11 +0200 Subject: [PATCH 50/52] Add more notes on the purpose of the operation descriptors --- .../elements/oneMKL/source/domains/spblas/operations/spmm.rst | 4 +++- .../elements/oneMKL/source/domains/spblas/operations/spmv.rst | 4 +++- .../elements/oneMKL/source/domains/spblas/operations/spsv.rst | 4 +++- 3 files changed, 9 insertions(+), 3 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst index 1cc1e8506..4d902d07b 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst @@ -55,7 +55,9 @@ spmm_descr Defines ``spmm_descr_t`` as an opaque pointer to the incomplete type ``spmm_descr``. Each backend may provide a different implementation of the - type ``spmm_descr``. + type ``spmm_descr``. The ``spmm_descr_t`` object persists through the various + stages of the spmm operation to house relevant state, optimizations and + workspaces. .. _onemkl_sparse_init_spmm_descr: diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst index ce743ba8d..ffcc207a4 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst @@ -55,7 +55,9 @@ spmv_descr Defines ``spmv_descr_t`` as an opaque pointer to the incomplete type ``spmv_descr``. Each backend may provide a different implementation of the - type ``spmv_descr``. + type ``spmv_descr``. The ``spmv_descr_t`` object persists through the various + stages of the spmv operation to house relevant state, optimizations and + workspaces. .. _onemkl_sparse_init_spmv_descr: diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst index c57977219..7bd9ced50 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst @@ -55,7 +55,9 @@ spsv_descr 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``. + type ``spsv_descr``. The `spsv_descr_t` object persists through the various + stages of the spsv operation to house relevant state, optimizations and + workspaces. .. _onemkl_sparse_init_spsv_descr: From 1c236f79e92452c964ab547b847b9d45ad9812eb Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Tue, 7 May 2024 14:17:15 +0200 Subject: [PATCH 51/52] Disallow changing sparse matrices before calling gemm or gemv --- .../oneMKL/source/domains/spblas/operations/spmm.rst | 7 +++---- .../oneMKL/source/domains/spblas/operations/spmv.rst | 7 +++---- .../oneMKL/source/domains/spblas/operations/spsv.rst | 4 +++- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst index 4d902d07b..5bfb5d515 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst @@ -273,10 +273,9 @@ spmm before ``spmm`` with the same arguments. ``spmm`` can then be called multiple times. Calling ``spmm_optimize`` on the same descriptor can reset some of the descriptor's data such as the ``workspace``. - - The data of the sparse handle ``A_handle`` can be reset-ed before each call - to ``spmm`` as long as the sparsity pattern stays the same. The data of the - dense handles ``B_handle`` and ``C_handle`` can be reset-ed before each - call to ``spmm``. + - The data of the dense handles ``B_handle`` and ``C_handle`` and the scalars + ``alpha`` and ``beta`` can be reset before each call to ``spmm``. Changing + the data of the sparse handle ``A_handle`` is undefined behavior. - ``spmm_optimize`` and ``spmm`` are asynchronous. - The algorithm defaults to ``spmm_alg::default_alg`` if a backend does not support the provided algorithm. diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst index ffcc207a4..5287b3a85 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst @@ -267,10 +267,9 @@ spmv before ``spmv`` with the same arguments. ``spmv`` can then be called multiple times. Calling ``spmv_optimize`` on the same descriptor can reset some of the descriptor's data such as the ``workspace``. - - The data of the sparse handle ``A_handle`` can be reset-ed before each call - to ``spmv`` as long as the sparsity pattern stays the same. The data of the - dense handles ``x_handle`` and ``y_handle`` can be reset-ed before each - call to ``spmv``. + - The data of the dense handles ``x_handle`` and ``y_handle`` and the scalars + ``alpha`` and ``beta`` can be reset before each call to ``spmv``. Changing + the data of the sparse handle ``A_handle`` is undefined behavior. - ``spmv_optimize`` and ``spmv`` are asynchronous. - The algorithm defaults to ``spmv_alg::default_alg`` if a backend does not support the provided algorithm. diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst index 7bd9ced50..1ddb9bf11 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst @@ -258,7 +258,9 @@ spsv 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``. - - The data of the dense handle ``x_handle`` can be reset-ed before each call to ``spsv``. + - 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. - ``spsv_optimize`` and ``spsv`` are asynchronous. - The algorithm defaults to ``spsv_alg::default_alg`` if a backend does not support the provided algorithm. From 62bbc6e6ac2694a94d9421bd3705d73d7e6dd809 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Tue, 7 May 2024 17:42:46 +0200 Subject: [PATCH 52/52] Fix warning --- .../source/domains/spblas/data_types/set_matrix_property.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_property.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_property.rst index 6c5a94831..0bbd44854 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_property.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_property.rst @@ -44,7 +44,7 @@ Matrix properties | For CSR this guarantees that the column indices are sorted in ascending order for a given row. | For COO this guarantees that the indices are sorted by row then by - column in ascending order. + column in ascending order. set_matrix_property -------------------