.. _ShellMatrix_MATMUL:

######
MATMUL
######

The following contains all relevant function for the **matrix-free** matrix-vector multiplication.
Depending on the setup (:ref:`MPI<MPI_docs>`, :ref:`openMP<openMP_docs>`, or **none**) different implementations are utilized of the same functions.

For distributed memory with :ref:`MPI<MPI_docs>`, a different set of routines (blocking -- which is the **default** -- and non-blocking) are available.
If ``MATMUL_NON_BLOCKING`` is defined via

.. code-block:: cpp

    #define MATMUL_NON_BLOCKING 1

the multiplication is done using non-blocking routines (**MPI_ISend** and **MPI_IRecv**) instead of **MPI_Alltoallv**.

Vector class
------------

The :ref:`Vector class<Vector>` can be used for computations executed by the :ref:`ShellMatrix<ShellMatrix>`.
In order to ensure the correct memory layout (particularly important for :ref:`MPI<MPI_docs>`), the :ref:`Vector<Vector>` instances should be created with:

.. _ShellMatrix_MATMUL_create_Vector:

.. doxygenfunction:: danceq::internal::ShellMatrix::create_Vector(void) const

.. _ShellMatrix_MATMUL_High_level:

High-level functions
--------------------

**Matrix-free** multiplication and the computation of the expectation value are performed using the following high-level functions that are wrapper for functions listed :ref:`below<ShellMatrix_MATMUL_Low_level>`.

.. doxygenfunction:: danceq::internal::ShellMatrix::apply(const danceq::internal::Vector<scalartype>& input, danceq::internal::Vector<scalartype>& output, const bool reset_output_to_zero = true) const

.. doxygenfunction:: danceq::internal::ShellMatrix::operator*(const Vector<scalartype>& input) const

.. _ShellMatrix_MATMUL_get_expectation_value:

.. doxygenfunction:: danceq::internal::ShellMatrix::get_expectation_value(const danceq::internal::Vector<scalartype>& lhs, const danceq::internal::Vector<scalartype>& rhs) const

.. _ShellMatrix_MATMUL_get_expectation_value_A:

.. doxygenfunction:: danceq::internal::ShellMatrix::get_expectation_value(const danceq::internal::Vector<scalartype>& psi) const

.. _ShellMatrix_MATMUL_Low_level:

Low-level functions
-------------------

We have two low-level function that are marked as ``private`` to compute the **matrix-free** matrix-vector multiplication and the expectation value of an :ref:`Operator<Operator>`.
They are called by higher-level, more user friendly, functions listed :ref:`above<ShellMatrix_MATMUL_High_level>`.

.. _ShellMatrix_MATMUL_MAMTUL_basic:

.. doxygenfunction:: danceq::internal::ShellMatrix::MATMUL_basic(const scalartype* input, scalartype* output, const bool reset_output_to_zero = true) const

.. _ShellMatrix_MATMUL_EXPECTATION_VALUE_basic:

.. doxygenfunction:: danceq::internal::ShellMatrix::EXPECTATION_VALUE_basic(const scalartype* lhs, const scalartype* rhs) const