.. _Operator_Functions_Frontends:

##############
Matrix Formats
##############

We provide different frontends for high-performance linear algebra packages like :ref:`Petsc and Slepc<Petsc_setup>` and :ref:`Eigen<Eigen_setup>`.
Respective functions are available if the libraries are included.

For dense operations (*e.g.*, determining the full spectrum), a dense matrix with :ref:`Eigen<Eigen_setup>` is returned by :ref:`create_EigenDenseMatrix(...)<Operator_Functions_Frontends_create_EigenDenseMatrix>`.
:ref:`Eigen<Eigen_setup>` can be combined using different `LAPACK <https://de.wikipedia.org/wiki/LAPACK>`_ libraries such as `Intel's MKL <https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html>`_.
For sparse operations (*e.g.*, `Krylov space <https://en.wikipedia.org/wiki/Krylov_subspace>`_ methods), we recommend using :ref:`Petsc and Slepc<Petsc_setup>`.
The libraries exploit the sparsity of the matrices and utilize the full power of a computing cluster by distributing tasks over several nodes.
:ref:`create_PetscSparseMatrix(...)<Operator_Functions_Frontends_create_PetscSparseMatrix>` returns the sparse matrix that can be used for different routines in `Slepc <https://slepc.upv.es/>`_.
Equivalently, :ref:`create_PetscShellMatrix(...)<Operator_Functions_Frontends_create_PetscShellMatrix>` returns a matrix shell allowing **matrix-free** multiplications.
Typically, the memory consumption is reduced by the system size but with increased run time.


Furthermore, :ref:`create_DenseMatrix()<Operator_Functions_Frontends_create_DenseMatrix>` and :ref:`create_SparseMatrix()<Operator_Functions_Frontends_create_SparseMatrix>` return the matrix in a dense format using ``std::vector`` and a sparse matrix using the :ref:`SparseMatrix class<SparseMatrix>`.
The functions are available without :ref:`Petsc<Petsc_setup>` or :ref:`Eigen<Eigen_setup>`.

All return functions are parallelized -- if possible.
Functions using native **cpp** container and :ref:`Eigen<Eigen_setup>` work with `OpenMP <https://www.openmp.org/>`_.
The :ref:`Petsc<Petsc_setup>` frontends use `MPI <https://de.wikipedia.org/wiki/Message_Passing_Interface>`_.


.. _Operator_Functions_Frontends_create_ShellMatrix:

.. doxygenfunction:: danceq::internal::Operator::create_ShellMatrix(const bool show_info = true, const double overhead_in_GB_per_core = 2.) const


.. _Operator_Functions_Frontends_create_PetscSparseMatrix:

.. doxygenfunction:: danceq::internal::Operator::create_PetscSparseMatrix(const bool show_info = false)

.. _Operator_Functions_Frontends_create_PetscShellMatrix:

.. doxygenfunction:: danceq::internal::Operator::create_PetscShellMatrix(const bool show_info = true, const double overhead_in_GB_per_core = 2.) const

.. _Operator_Functions_Frontends_create_EigenDenseMatrix:

.. doxygenfunction:: danceq::internal::Operator::create_EigenDenseMatrix(void) const

.. _Operator_Functions_Frontends_create_DenseMatrix:

.. doxygenfunction:: danceq::internal::Operator::create_DenseMatrix(void) const

.. _Operator_Functions_Frontends_create_SparseMatrix:

.. doxygenfunction:: danceq::internal::Operator::create_SparseMatrix(void)