.. _ShellMatrix:

###########
ShellMatrix
###########


The :ref:`ShellMatrix class<ShellMatrix_Autodocs>` is a core feature of :ref:`DanceQ<DanceQ>`.
By providing an :ref:`Operator<Operator>`, it allows a **matrix-free** matrix-vector multiplication using the :ref:`Vector class<Vector>`.
Not storing the matrix yields an increased runtime, but reduces the memory significantly allowing the access to much larger systems.
In particular, acting on a Hilbert space spanned by :math:`L` sites, utilizing the **matrix-free** routines of the :ref:`ShellMatrix<ShellMatrix>` reduces the memory cost by :math:`L` for ground-state searches.
Computing the ground state for a system with :math:`L=42` at half-filling (:math:`S=1/2`) requires a large computing center with up to :math:`160` TB. 
In contrast, the **matrix-free** computation reduces the memory cost to :math:`4` TB which becomes now possible with a few computing nodes.

The routines are highly optimized and support distributed memory with :ref:`MPI<MPI_docs>` and shared memory with :ref:`openMP<openMP_docs>`.
Note, that no third-party libraries like :ref:`Eigen<Eigen_setup>` or :ref:`Petsc/Slepc<Petsc_setup>` are required.
If :ref:`MPI<MPI_docs>` has been found, it is used.
If this is not the case and :ref:`openMP<openMP_docs>` is available, the program is parallelized using :ref:`openMP<openMP_docs>`.
If no parallelization option is given, the code is executed serially. 

.. code-block:: cpp

    /* Retrieving the ShellMatrix from the Operator class */
    auto H = H_operator.create_ShellMatrix();

    /* Retrieving the Vector from the ShellMatrix class */
    auto v = H.create_Vector();

    /* Random initialization of the Vector */
    v.make_random();

    /* Matrix-free multiplication */
    auto w = H*v;

    /* Output */
    w.print();

    /* Expectation value */
    auto val0 = H.get_expectation_value(v,v);

    /* val1 equals val0 */
    auto val1 = w*v;


.. note::

    The syntax is equivalent for :ref:`MPI<MPI_docs>` and :ref:`openMP<openMP_docs>`!

A full example for distributed and shared memory is available in the repository as discussed :ref:`here<Examples_ShellMatrix>`.
It computes multiple ground states.

Petsc wrapper
-------------

The following functions are only available if :ref:`Petsc<Petsc_setup>` has been included.
The :ref:`ShellMatrix class<ShellMatrix>` is internally used by :ref:`Petsc<Petsc_setup>` to create a `MATSHELL <https://petsc.org/release/manualpages/Mat/MATSHELL/>`_ object that behaves like a *normal* matrix and can be used for various functions within :ref:`Petsc/Slepc<Petsc_setup>`.
It works with the :ref:`Petsc<Petsc_setup>` vector structure `Vec <https://petsc.org/main/manualpages/Vec/>`_ which distributes the memory over all :ref:`MPI ranks<MPI_docs>`.
See :ref:`this exmaple<Examples>` for more information.
The `Petsc MATSHELL <https://petsc.org/release/manualpages/Mat/MATSHELL/>`_ can be simply retrieved from an :ref:`Operator<Operator>` via :ref:`create_PetscShellMatrix()<Operator_Functions_Frontends_create_PetscShellMatrix>`:

.. code-block:: cpp

    /* MATHELL Petsc object using the ShellMatrix class */
    auto H_MATSHELL = H.create_PetscShellMatrix();


The necassary functions are listed in:

.. toctree::
    :maxdepth: 1
    :titlesonly:

    ShellMatrix/Petsc.rst

Datatypes
---------

The underlying scalar **scalartype**, its real part **scalartype_real**, and the :ref:`State class<State>` **state_class** can be retrieved from an instance:

.. doxygentypedef:: danceq::internal::ShellMatrix::scalartype

.. doxygentypedef:: danceq::internal::ShellMatrix::scalartype_real

.. doxygentypedef:: danceq::internal::ShellMatrix::state_class

Class content
-------------


.. toctree::
    :maxdepth: 2
    :titlesonly:


    ShellMatrix/Members.rst
    ShellMatrix/Constructors.rst
    ShellMatrix/Functions.rst
    ShellMatrix/Autodocs.rst