.. _State_Functions:

*********
Functions
*********



The :ref:`State class<State>` comes with broad functionality to read and modify a :ref:`state<State>`.
The most important functions are listed here.
To access specific sites of an instance of the :ref:`State class<State>`, functions in :ref:`State_Read_Functions` can be used.
Different functions to modify a :ref:`state<State>` are defined in :ref:`State_Modify_Functions`.
Many information and the :ref:`state<State>` itself can be printed using the functions in :ref:`State_Output_Functions`.
In many cases, two instances of the :ref:`State class<State>` have to be compared.
Greater, lesser, and equal are defined on the integer **and** qudit-level in :ref:`State_Comp_Functions`.
Simple getter functions returning template parameters and further information are listed in :ref:`State_Getter_Functions`.





Furthermore, the :ref:`State class<State>` already provides a sufficient toolbox to enumerate basis states :math:`\vert \Psi_i\rangle`.
The set functions are defined within a range **start** to **end**.
These functions can -- *in pinciple* -- be used as a complete :ref:`Basis<Basis_General>` with **and** without number conservation.
However, the implementation is not as efficient as the :ref:`Basis class<BasisU1>`.


* **Enumeration without number conservation**:

    The first enumeration refers to the complete integer counting to basis :math:`Q` defined within site **start** and **end**:

    .. math::
        :name: eq:state_functions_integer_counting

        \textbf{index} = \sum_{i=\textbf{start}}^{\textbf{end}-1} \quad \sigma_i \cdot\textbf{Q}^{i-\textbf{start}}
        

    A complete set of functions is listed in :ref:`State_No_Conserve_Functions`.
    This includes iterators (forward and backward) and a mapping between an **index**, :math:`i\in\{0,\dots,Q^L-1\}`, and its physical State :math:`\vert\Psi_i\rangle` and *vice versa*.

* **Enumeration with number conservation**:

    The second enumeration procedure takes additionally the particle number between site **start** and **end** into account:

    .. math::
        :name: eq:state_functions_particle_number

        \textbf{n} = \sum_{i=\textbf{start}}^{\textbf{end}-1} \sigma_i

    The :ref:`state<State>` with **index** *i*, :math:`\vert\Psi_i\rangle`, is the *i* th :ref:`state<State>` in a given **particle sector** and all :ref:`states<state>` are ordered by :ref:`interger counting<eq:state_functions_integer_counting>` to the basis :math:`Q`.
    All functions can be found in :ref:`State_Conserve_Functions`.

* **Enumeration without number conservation and inhomogeneously distributed Q**:

    We further provide the option to work with a different local Hilbert space dimensions per site. 
    They are set by passing a ``std::vector`` containing all **Q**.
    The functions are listed :ref:`here<State_No_Conserve_Functions_IHQ>`.

  

.. warning::

   The enumeration is limited by the upper bound of **uint64_t**.


.. toctree::
    :maxdepth: 1
 
    Functions/No_Conserve_Functions.rst
    Functions/Conserve_Functions.rst
    Functions/Readout_Functions.rst
    Functions/Modify_Functions.rst
    Functions/Output_Functions.rst
    Functions/Comparison_Functions.rst
    Functions/Getter_Functions.rst
    Functions/Miscellaneous.rst