.. _oneapi-mkl-sparse-get_matmat_data:

oneapi::mkl::sparse::get_matmat_data
====================================

Queries the  ``oneapi::mkl::sparse::matrix_view_descr`` and ``oneapi::mkl::transpose`` values in the ``oneapi::mkl::sparse::matmat_descr_t`` object reflecting the ``sparse::matmat`` operation to be performed: :math:`C = \text{op}(A) \cdot \text{op}(B)`.


.. contents::
    :local:
    :depth: 1

Description
***********

The ``oneapi::mkl::sparse::get_matmat_data`` routine allows user to query the enum values set for the sparse matrix - sparse matrix operation in the ``oneapi::mkl::sparse::matmat_descr_t`` object which will be used in the :ref:`sparse::matmat<oneapi-mkl-sparse-matmat>` routine.

The ``oneapi::mkl::sparse::matrix_view_descr`` enum class is defined in the ``oneapi/mkl/spblas.hpp`` header file

.. code-block:: cpp

    namespace oneapi::mkl::sparse {
        enum class matrix_view_descr : std::int32_t {
            general
        };
    }

where general view assumes all data is populated in the ``sparse::matrix_handle_t`` object for both lower, diagonal and upper portions of the matrix. A common usage model for the ``matmat`` descriptor is the following:

.. code-block:: cpp

    using namespace oneapi::mkl;
    sparse::matmat_descr_t descr = NULL;
    sparse::init_matmat_descr(descr);
    // someone sets matmat descr

    // query what was in descr
    sparse::matrix_view_descr viewA, viewB, viewC;
    transpose opA, opB;
    sparse::get_matmat_data(descr, viewA, opA, viewV, opB, viewC);

    sparse::release_matmat_descr(descr);


API
***

Syntax
------

.. code-block:: cpp

    namespace oneapi::mkl::sparse {
        void get_matmat_descr (
            sparse::matmat_descr_t    descr,
            sparse::matrix_view_descr &viewA,
            transpose                 &opA,
            sparse::matrix_view_descr &viewB,
            transpose                 &opB,
            sparse::matrix_view_descr &viewC);
    }



Include Files
-------------

-  oneapi/mkl/spblas.hpp


Input Parameters
----------------

descr
   ``sparse::matmat_descr_t`` object used to define the sparse matrix - sparse matrix operation to be performed by the :ref:`sparse::matmat<oneapi-mkl-sparse-matmat>` routine.


Output Parameters
-----------------

viewA, viewB, viewC
    ``sparse::matrix_view_descr`` enum values describing how the :math:`A`, :math:`B` and :math:`C` matrix represenatations should be viewed. Currently, only the `general` type is supported.

opA, opB
   Specifies operation ``op()`` on input matrix.

   .. list-table::
      :header-rows: 0

      * -  ``oneapi::mkl::transpose::nontrans``
        -  Non-transpose, :math:`\text{op}(A) = A`.
      * -  ``oneapi::mkl::transpose::trans``
        -  Transpose, :math:`\text{op}(A) = A^{T}`.
      * -  ``oneapi::mkl::transpose::conjtrans``
        -  Conjugate transpose, :math:`\text{op}(A) = A^{H}`.

   .. note::
      Currently, the only supported case for operation is ``oneapi::mkl::transpose::nontrans``.