.. _Basis_General:

#####
Basis
#####

Given a total particle number, say :math:`n`, all :ref:`states<State>` with this particle number or magnetization are enumerated with the :ref:`Basis<BasisU1>`:

.. math::
   \vert\Psi\rangle = \vert\sigma_0\rangle \otimes \vert\sigma_1\rangle \dots \otimes \vert\sigma_{N-1}\rangle = \vert\sigma_0;\dots;\sigma_{N-1}\rangle \quad\mathrm{ with }\quad n = \sum_{i=0}^{N-1} \sigma_i


Let's have a look at a small example for :math:`N=4` local sites with :math:`Q=3` and :math:`n=3`:


+------------------------------------------------------+------------------------------------------------------+------------------------------------------------------+------------------------------------------------------+
| :math:`\vert\Psi_0   \rangle = \vert 0;0;1;2\rangle` | :math:`\vert\Psi_1   \rangle = \vert 0;0;2;1\rangle` | :math:`\vert\Psi_2   \rangle = \vert 0;1;0;2\rangle` | :math:`\vert\Psi_3   \rangle = \vert 0;1;1;1\rangle` |
+------------------------------------------------------+------------------------------------------------------+------------------------------------------------------+------------------------------------------------------+
| :math:`\vert\Psi_4   \rangle = \vert 0;1;2;0\rangle` | :math:`\vert\Psi_5   \rangle = \vert 0;2;0;1\rangle` | :math:`\vert\Psi_6   \rangle = \vert 0;2;1;0\rangle` | :math:`\vert\Psi_7   \rangle = \vert 1;0;0;2\rangle` |
+------------------------------------------------------+------------------------------------------------------+------------------------------------------------------+------------------------------------------------------+
| :math:`\vert\Psi_8   \rangle = \vert 1;0;1;1\rangle` | :math:`\vert\Psi_9   \rangle = \vert 1;0;2;0\rangle` | :math:`\vert\Psi_{10}\rangle = \vert 1;1;0;1\rangle` | :math:`\vert\Psi_{11}\rangle = \vert 1;1;1;0\rangle` |
+------------------------------------------------------+------------------------------------------------------+------------------------------------------------------+------------------------------------------------------+
| :math:`\vert\Psi_{12}\rangle = \vert 1;2;0;0\rangle` | :math:`\vert\Psi_{13}\rangle = \vert 2;0;0;1\rangle` | :math:`\vert\Psi_{14}\rangle = \vert 2;0;1;0\rangle` | :math:`\vert\Psi_{15}\rangle = \vert 2;1;0;0\rangle` |
+------------------------------------------------------+------------------------------------------------------+------------------------------------------------------+------------------------------------------------------+

Enumerating all :ref:`basis states<State>` quickly becomes tricky for larger systems as the complexity scales exponentially.
This is efficiently solved by splitting the large system of size **L** in **Npart** subsystems.
A detailed explanations and analysis can be found in the :ref:`paper<Paper>`.

Basic setup
-----------


There are multiple classes that are built on top of the :ref:`State class<State>`:

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

    Basis/Container.rst
    Basis/BasisU1.rst
    Basis/Iterator.rst

.. admonition:: Hierarchy of classes

    :math:`\qquad` :ref:`State<State>` :math:`\quad\stackrel{\mathrm{defines}}{\Longrightarrow}\quad` :ref:`Container<Container>` :math:`\quad\stackrel{\mathrm{defines}}{\Longrightarrow}\quad` :ref:`BasisU1 class<BasisU1>` :math:`\quad\stackrel{\mathrm{defines}}{\Longrightarrow}\quad` :ref:`Basis Iterator<Iterator>`


The main functionality to merge the individual systems is contained in the :ref:`BasisU1 class<BasisU1>` that includes all tools to enumerate and generate the :ref:`basis states<State>`.
The individual subsystems are organized in a :ref:`Container class<Container>`.
Note that we provide three different implementations of the :ref:`Container<Container>`, which are discussed in detail in the :ref:`paper<Paper>` and :ref:`here<Container>`.
The :ref:`BasisU1 class<BasisU1>` is generated from the :ref:`State class<State>` and the :ref:`Container class<Container>`.
On top of :ref:`BasisU1 class<BasisU1>`, an :ref:`iterator class<Iterator>` -- built from the :ref:`BasisU1 class<BasisU1>` -- allows an easy handling in **C++** style.

All classes are built on top of each other with the underlying the :ref:`State class<State>`.
They can be defined in the following way:

.. code-block:: cpp

    #include "Basis.h"

    /* Defining the state class with a maximal length of 256 sites and a local dimension of 4 */
    using State = danceq::internal::State<256,4>; 

    /* Defining a Container class from the State class */
    using Container = danceq::internal::ContainerTable<State>; 
    /* Instead of the ContainerTable<State> you can call:
     * using Container = danceq::internal::ContainerDict<State>;
     * using Container = danceq::internal::ContainerFly<State>;
     */

    /* Defining the Basis class from the Container class */
    using Basis = danceq::internal::BasisU1<Container>; 

    /* Defining the Basis class from the State Class with ContainerTable<State> */
    using Basis_from_State = danceq::internal::BasisU1<State>; 

    /* Defining the Iterator from the Basis class */
    using BasisIterator = danceq::internal::BasisIterator<Basis>;

    /* It is possible to retrieve the underlying State class */
    Basis::state_class state;

Additionally, we have you defined the type  ``danceq::internal::Basis<T>`` that can be built from a :ref:`Container class<Container>` and the :ref:`State class<State>`.
In the case of the :ref:`State class<State>`, :ref:`ContainerTable\<State\><ContainerTable>` is used.

Code examples are given :ref:`here<Examples_Basis>`.