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 23916970ff..b48583bd72 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,29 +9,24 @@ Sparse Linear Algebra .. container:: - - 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. - - - 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 - an opaque pointer, used to store data related to initial sparse matrix - and data obtained during analysis stage. - + 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 + 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 + 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. Each operation has a descriptor type + that is used to carry information across the different stages. .. toctree:: - :hidden: + :hidden: - spblas/spblas.rst + spblas/spblas.rst 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 0000000000..dfcf922121 --- /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_init_dense_vector` + - :ref:`onemkl_sparse_set_dense_vector_data` + - :ref:`onemkl_sparse_release_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_init_dense_matrix` + - :ref:`onemkl_sparse_set_dense_matrix_data` + - :ref:`onemkl_sparse_release_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_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_property` + - :ref:`onemkl_sparse_release_sparse_matrix` + + See a description of the supported :ref:`sparse formats`. + +.. toctree:: + :hidden: + + 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 + set_matrix_property + format-descriptions + +**Parent topic:** :ref:`onemkl_spblas` 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 0000000000..33ab4b153a --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/data_types/format-descriptions.rst @@ -0,0 +1,155 @@ +.. 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. + +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: + + .. 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. 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, 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 + + .. 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. 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. 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 non-zero 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/init_coo_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/init_coo_matrix.rst new file mode 100644 index 0000000000..7f955e388f --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/data_types/init_coo_matrix.rst @@ -0,0 +1,251 @@ +.. SPDX-FileCopyrightText: 2024 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_sparse_init_coo_matrix: + +init_coo_matrix +=============== + +Initializes a ``matrix_handle_t`` object with the provided COO data. + +.. rubric:: Description and Assumptions + +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 ``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::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 +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`. + +.. _onemkl_sparse_init_coo_matrix_buffer: + +init_coo_matrix (Buffer version) +-------------------------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + template + 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); + + } + +.. container:: section + + .. rubric:: Template parameters + + dataType + See :ref:`supported template types`. + + indexType + 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 + 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 + in :ref:`onemkl_enum_index_base` enum class. + + 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 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 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 + + .. 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:: 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 + + 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_init_coo_matrix_usm: + +init_coo_matrix (USM version) +----------------------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + template + 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); + + } + +.. container:: section + + .. rubric:: Template parameters + + dataType + See :ref:`supported template types`. + + indexType + 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 + 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 + in :ref:`onemkl_enum_index_base` enum class. + + row_ind + 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 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 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 + + .. 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:: 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 + + 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` + +**Parent topic:** :ref:`onemkl_sparse_data_handles` 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 new file mode 100644 index 0000000000..cf8a14eb21 --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/data_types/init_csr_matrix.rst @@ -0,0 +1,250 @@ +.. SPDX-FileCopyrightText: 2024 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_sparse_init_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::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 ``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::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 +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`. + +.. _onemkl_sparse_init_csr_matrix_buffer: + +init_csr_matrix (Buffer version) +-------------------------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + template + 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); + + } + +.. container:: section + + .. rubric:: Template parameters + + dataType + See :ref:`supported template types`. + + indexType + 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 + 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 + in :ref:`onemkl_enum_index_base` enum class. + + 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 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 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 + + .. 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:: 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 + + 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_init_csr_matrix_usm: + +init_csr_matrix (USM version) +----------------------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + template + 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); + + } + +.. container:: section + + .. rubric:: Template parameters + + dataType + See :ref:`supported template types`. + + indexType + 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 + 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 + in :ref:`onemkl_enum_index_base` enum class. + + row_ptr + 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 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 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 + + .. 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:: 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 + + 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` + +**Parent topic:** :ref:`onemkl_sparse_data_handles` 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 new file mode 100644 index 0000000000..15c37b4986 --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/data_types/init_dense_matrix.rst @@ -0,0 +1,191 @@ +.. SPDX-FileCopyrightText: 2024 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_sparse_init_dense_matrix: + +init_dense_matrix +================= + +Initializes a ``dense_matrix_handle_t`` object with the provided data. + +.. rubric:: Description and Assumptions + +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 ``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_init_dense_matrix_buffer: + +init_dense_matrix (Buffer version) +---------------------------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + template + 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); + + } + +.. container:: section + + .. rubric:: Template parameters + + dataType + 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 1. + + num_cols + 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 + ``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 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. + +.. 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::host_bad_alloc` + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::unsupported_device` + +.. _onemkl_sparse_init_dense_matrix_usm: + +init_dense_matrix (USM version) +------------------------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + template + 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); + + } + +.. container:: section + + .. rubric:: Template parameters + + dataType + 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 1. + + num_cols + 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 + ``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 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. Using a + USM pointer with a smaller allocated memory size is undefined behavior. + +.. 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::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/init_dense_vector.rst b/source/elements/oneMKL/source/domains/spblas/data_types/init_dense_vector.rst new file mode 100644 index 0000000000..50b6de6c78 --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/data_types/init_dense_vector.rst @@ -0,0 +1,161 @@ +.. SPDX-FileCopyrightText: 2024 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_sparse_init_dense_vector: + +init_dense_vector +================= + +Initializes a ``dense_vector_handle_t`` object with the provided data. + +.. rubric:: Description and Assumptions + +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 ``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_init_dense_vector_buffer: + +init_dense_vector (Buffer version) +---------------------------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + template + void init_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 + + dataType + 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 1. + + val + Buffer of length at least ``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::host_bad_alloc` + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::unsupported_device` + +.. _onemkl_sparse_init_dense_vector_usm: + +init_dense_vector (USM version) +------------------------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + template + void init_dense_vector (sycl::queue &queue, + oneapi::mkl::sparse::dense_vector_handle_t *p_dvhandle, + std::int64_t size, + dataType *val); + + } + +.. container:: section + + .. rubric:: Template parameters + + dataType + 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 1. + + val + USM pointer of length at least ``size``. Holds the data to initialize + ``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 + + .. 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::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/release_dense_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/release_dense_matrix.rst new file mode 100644 index 0000000000..2d77606e11 --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/data_types/release_dense_matrix.rst @@ -0,0 +1,67 @@ +.. SPDX-FileCopyrightText: 2024 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_sparse_release_dense_matrix: + +release_dense_matrix +==================== + +Destroys a ``dense_matrix_handle_t`` object. + +.. rubric:: Description and Assumptions + +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. + +If a USM pointer was provided, the data is not free'd. + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + sycl::event release_dense_matrix (sycl::queue &queue, + oneapi::mkl::sparse::dense_matrix_handle_t dmhandle, + const std::vector &dependencies = {}); + + } + +.. 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_init_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 + + 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/release_dense_vector.rst b/source/elements/oneMKL/source/domains/spblas/data_types/release_dense_vector.rst new file mode 100644 index 0000000000..73b1860489 --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/data_types/release_dense_vector.rst @@ -0,0 +1,67 @@ +.. SPDX-FileCopyrightText: 2024 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_sparse_release_dense_vector: + +release_dense_vector +==================== + +Destroys a ``dense_vector_handle_t`` object. + +.. rubric:: Description and Assumptions + +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. + +If a USM pointer was provided, the data is not free'd. + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + sycl::event release_dense_vector (sycl::queue &queue, + oneapi::mkl::sparse::dense_vector_handle_t dvhandle, + const std::vector &dependencies = {}); + + } + +.. 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_init_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 + + 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/release_sparse_matrix.rst b/source/elements/oneMKL/source/domains/spblas/data_types/release_sparse_matrix.rst new file mode 100644 index 0000000000..d1d549335f --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/data_types/release_sparse_matrix.rst @@ -0,0 +1,68 @@ +.. SPDX-FileCopyrightText: 2024 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_sparse_release_sparse_matrix: + +release_sparse_matrix +===================== + +Destroys a ``matrix_handle_t`` object. + +.. rubric:: Description and Assumptions + +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. + +If a USM pointer was provided, the data is not free'd. + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + sycl::event release_sparse_matrix (sycl::queue &queue, + oneapi::mkl::sparse::matrix_handle_t smhandle, + const std::vector &dependencies = {}); + + } + +.. 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_init_csr_matrix` or + :ref:`onemkl_sparse_init_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 + + .. 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/set_coo_matrix_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst new file mode 100644 index 0000000000..a6dba2712d --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst @@ -0,0 +1,225 @@ +.. 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 ``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_init_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 + + dataType + See :ref:`supported template types`. Can be + a different type than what was used when creating the ``matrix_handle_t``. + + indexType + 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_init_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 + 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 + in :ref:`onemkl_enum_index_base` enum class. + + 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 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 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 + + .. 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 + + 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` + +.. _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, + indexType *row_ind, + indexType *col_ind, + dataType *val); + + } + +.. container:: section + + .. rubric:: Template parameters + + dataType + See :ref:`supported template types`. Can be + a different type than what was used when creating the ``matrix_handle_t``. + + indexType + 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_init_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 + 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 + in :ref:`onemkl_enum_index_base` enum class. + + row_ind + 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 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 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 + + .. 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 + + 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/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 0000000000..3a28785d0f --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst @@ -0,0 +1,223 @@ +.. 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 ``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_init_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 + + dataType + See :ref:`supported template types`. Can be + a different type than what was used when creating the ``matrix_handle_t``. + + indexType + 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_init_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 + 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 + in :ref:`onemkl_enum_index_base` enum class. + + 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 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 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 + + .. 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 + + 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` + +.. _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, + indexType *row_ptr, + indexType *col_ind, + dataType *val); + + } + +.. container:: section + + .. rubric:: Template parameters + + dataType + See :ref:`supported template types`. Can be + a different type than what was used when creating the ``matrix_handle_t``. + + indexType + 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_init_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 + 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 + in :ref:`onemkl_enum_index_base` enum class. + + row_ptr + 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 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 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 + + .. 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 + + 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/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 0000000000..c75a80e742 --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst @@ -0,0 +1,174 @@ +.. 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 ``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_init_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 + + dataType + 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_init_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 at least ``ld*num_cols`` if column major is used or + ``ld*num_rows`` if row major is used. + +.. 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` + +.. _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, + dataType *val); + + } + +.. container:: section + + .. rubric:: Template parameters + + dataType + 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_init_dense_matrix`. + + num_rows + 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 1. + + 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 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. Using a USM pointer with a smaller allocated memory size is + undefined behavior. + +.. 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/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 0000000000..844e73bf70 --- /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 ``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_init_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 + + dataType + 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_init_dense_vector`. + + size + Number of elements of the provided data ``val``. Must be at least 0. + + val + Buffer of length at least ``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::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, + dataType *val); + + } + +.. container:: section + + .. rubric:: Template parameters + + dataType + 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_init_dense_vector`. + + size + 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 + the device. Using a USM pointer with a smaller allocated memory size is + undefined behavior. + +.. 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/data_types/set_matrix_property.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_property.rst new file mode 100644 index 0000000000..0bbd44854f --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_property.rst @@ -0,0 +1,105 @@ +.. 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 + + namespace oneapi::mkl::sparse { + + enum class matrix_property { + symmetric, + sorted, + }; + + } + + 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. Multiple properties can be set to the same handle. + + .. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - Value + - Description + * - ``symmetric`` + - 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 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 the indices are sorted by row then by + column in ascending order. + +set_matrix_property +------------------- + +Set a property 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. + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + bool set_matrix_property (sycl::queue &queue, + oneapi::mkl::sparse::matrix_handle_t smhandle, + matrix_property property); + + } + +.. container:: section + + .. rubric:: Input parameters + + queue + The SYCL command queue which will be used for SYCL kernels execution. + + smhandle + Initialized sparse matrix handle. + + property + 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 an equivalent property. + +.. 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 6815ad61b8..0000000000 --- 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 bcc2bed6f4..0000000000 --- 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 235eff332a..0000000000 --- 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 48842583ec..0000000000 --- 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 b615e3bae6..0000000000 --- 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 4e0b6c5731..0000000000 --- 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 0000000000..c69069c58e --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/matrix_view.rst @@ -0,0 +1,130 @@ +.. 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 describes how an operation should interpret the data. + + .. 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` for a description of the members. + + The ``uplo_view`` member is ignored if ``type_view`` is ``general`` or + ``diagonal``. + + The ``diag_view`` member is ignored if ``type_view`` is ``general``. + + .. 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 66db350825..0000000000 --- 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 0000000000..5bfb5d5151 --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst @@ -0,0 +1,379 @@ +.. SPDX-FileCopyrightText: 2024 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_sparse_spmm_header: + +spmm +==== + +Computes a sparse matrix by dense matrix product. + +.. rubric:: Description and Assumptions + +The ``oneapi::mkl::sparse::spmm`` routine computes a sparse matrix by 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:`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:: + + \text{op}(A) = \begin{cases} A,& \text{oneapi::mkl::transpose::nontrans}\\ + A^\mathsf{T},& \text{oneapi::mkl::transpose::trans}\\ + A^\mathsf{H},& \text{oneapi::mkl::transpose::conjtrans} + \end{cases} + +.. _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``. 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: + +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 { + + sycl::event release_spmm_descr (sycl::queue &queue, + oneapi::mkl::sparse::spmm_descr_t spmm_descr, + const std::vector &dependencies = {}); + + } + +.. 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``. + + 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 + + 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, + no_optimize_alg, + coo_alg1, + coo_alg2, + coo_alg3, + coo_alg4, + csr_alg1, + csr_alg2, + csr_alg3, + }; + + } + +.. 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: + +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, + 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, + 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, + std::size_t &temp_buffer_size); + + void spmm_optimize( + sycl::queue &queue, + oneapi::mkl::transpose opA, + oneapi::mkl::transpose opB, + 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, + 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, + sycl::buffer workspace); + + sycl::event spmm_optimize( + sycl::queue &queue, + oneapi::mkl::transpose opA, + oneapi::mkl::transpose opB, + 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, + 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, + void* workspace, + const std::vector &dependencies = {}); + + sycl::event spmm( + sycl::queue &queue, + oneapi::mkl::transpose opA, + oneapi::mkl::transpose opB, + 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, + 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, + 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. Calling ``spmm_optimize`` on the same descriptor can reset + some of the descriptor's data such as the ``workspace``. + - 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. + - The container type of all the handles and ``workspace`` must be consistent + and use either USM pointers or SYCL buffers. + + .. 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. 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 + :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. 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`. + + 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 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 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 + data on the device. Ignored if buffers are used. Defaults to no dependencies. + +.. container:: section + + .. rubric:: Output Parameters + + temp_buffer_size + Output buffer size in bytes. A temporary workspace of at least this size + must be allocated to perform the specified 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. May be an empty event if buffers are used. + +.. 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 0000000000..5287b3a852 --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst @@ -0,0 +1,369 @@ +.. SPDX-FileCopyrightText: 2024 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_sparse_spmv_header: + +spmv +==== + +Computes a sparse matrix by dense vector product. + +.. rubric:: Description and Assumptions + +The ``oneapi::mkl::sparse::spmv`` routine computes a sparse matrix by 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:`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:: + + \text{op}(A) = \begin{cases} A,& \text{oneapi::mkl::transpose::nontrans}\\ + A^\mathsf{T},& \text{oneapi::mkl::transpose::trans}\\ + A^\mathsf{H},& \text{oneapi::mkl::transpose::conjtrans} + \end{cases} + +.. _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``. 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: + +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 { + + sycl::event release_spmv_descr (sycl::queue &queue, + oneapi::mkl::sparse::spmv_descr_t spmv_descr, + const std::vector &dependencies = {}); + + } + +.. 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``. + + 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 + + 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, + no_optimize_alg, + coo_alg1, + coo_alg2, + csr_alg1, + csr_alg2, + csr_alg3, + }; + + } + +.. 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: + +spmv +---- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + void spmv_buffer_size( + sycl::queue &queue, + oneapi::mkl::transpose opA, + 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, + 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, + std::size_t &temp_buffer_size); + + void spmv_optimize( + sycl::queue &queue, + oneapi::mkl::transpose opA, + 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, + 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, + sycl::buffer workspace); + + sycl::event spmv_optimize( + sycl::queue &queue, + oneapi::mkl::transpose opA, + 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, + 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, + void* workspace, + const std::vector &dependencies = {}); + + sycl::event spmv( + sycl::queue &queue, + oneapi::mkl::transpose opA, + 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, + 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, + 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. Calling ``spmv_optimize`` on the same descriptor can reset + some of the descriptor's data such as the ``workspace``. + - 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. + - The container type of all the handles and ``workspace`` must be consistent + and use either USM pointers or SYCL buffers. + + .. 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. 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 + :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. 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`. + + 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 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 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 + data on the device. Ignored if buffers are used. Defaults to no dependencies. + +.. container:: section + + .. rubric:: Output Parameters + + temp_buffer_size + Output buffer size in bytes. A temporary workspace of at least this size + must be allocated to perform the specified 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. May be an empty event if buffers are used. + +.. 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 0000000000..1ddb9bf110 --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst @@ -0,0 +1,356 @@ +.. SPDX-FileCopyrightText: 2024 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_sparse_spsv_header: + +spsv +==== + +Solves a system of linear equations where the coefficients are described by 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:`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:: + + \text{op}(A) = \begin{cases} A,& \text{oneapi::mkl::transpose::nontrans}\\ + A^\mathsf{T},& \text{oneapi::mkl::transpose::trans}\\ + A^\mathsf{H},& \text{oneapi::mkl::transpose::conjtrans} + \end{cases} + +.. _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``. 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: + +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 { + + sycl::event release_spsv_descr (sycl::queue &queue, + oneapi::mkl::sparse::spsv_descr_t spsv_descr, + const std::vector &dependencies = {}); + + } + +.. 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``. + + 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 + + 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, + no_optimize_alg, + }; + + } + +.. 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: + +spsv +---- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::sparse { + + void spsv_buffer_size( + sycl::queue &queue, + oneapi::mkl::transpose opA, + 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, + 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, + 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, + 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, + 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, + 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, + 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, + 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. 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`` 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. + - The container type of all the handles and ``workspace`` must be consistent + and use either USM pointers or SYCL buffers. + + .. 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. 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 + :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`. + + 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 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 or the workspace is + reset by ``spsv_optimize``. The workspace cannot be a sub-buffer. + | If it is a USM pointer, it must not be free'd until the corresponding + ``spsv`` has completed. The data must be accessible on the device. + + dependencies + List of events to depend on before starting asynchronous tasks that access + data on the device. Ignored if buffers are used. Defaults to no dependencies. + +.. container:: section + + .. rubric:: Output Parameters + + temp_buffer_size + Output buffer size in bytes. A temporary workspace of at least this size + must be allocated to perform the specified spsv. + + y_handle + Dense vector handle object representing :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. May be an empty event if buffers are used. + +.. 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 0cfd90e771..0000000000 --- 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 23b4b31a34..0000000000 --- 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 11c5e07c07..0000000000 --- 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 92f68a061c..eef2b3fb49 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_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: - - 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/spmm + operations/spmv + operations/spsv + 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 63cd517ee9..858f1a6999 100644 --- a/source/elements/oneMKL/source/domains/spblas/supported-types.rst +++ b/source/elements/oneMKL/source/domains/spblas/supported-types.rst @@ -1,42 +1,34 @@ -.. 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:: tablenoborder -.. container:: + .. list-table:: + :header-rows: 1 + * - Data Types ```` + - Integer Types ```` + * - ``float`` + - ``std::int32_t`` + * - ``double`` + - ``std::int64_t`` + * - ``std::complex`` + -   + * - ``std::complex`` + -   - .. container:: tablenoborder +``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. - .. list-table:: - :header-rows: 1 - - * - Data Types - - Integer Types - * - ``float`` - - ``std::int32_t`` - * - ``double`` - - ``std::int64_t`` - * - ``std::complex`` - -   - * - ``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 d0e7f81bf6..0000000000 --- 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 1ae6335f06..0000000000 --- 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 18f627e929..0000000000 --- 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 67bb143e2d..0000000000 --- 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 b55b6e4dde..0000000000 --- a/source/elements/oneMKL/source/domains/spblas/trsv.rst +++ /dev/null @@ -1,227 +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) \cdot y \leftarrow \alpha \cdot 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``, and :math:`\alpha` is a scalar value. - -.. _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 opA, - oneapi::mkl::diag diag_val, - const fp alpha, - 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. - - - opA - 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)`. - - -.. 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 opA, - oneapi::mkl::diag diag_val, - const fp alpha, - 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. - - - opA - 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)`. - - - 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 805f3308ec..0000000000 --- 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`