.. _State:

*****
State
*****



The :ref:`State class<State>` provides a primitive container to store and manipulate a product state of qudits:

.. math::
   \vert\Psi\rangle = \vert\sigma_0\rangle \otimes \vert\sigma_1\rangle \dots \otimes \vert\sigma_{N-1}\rangle\,.

Each site is represented by a local Hilbert space :math:`\vert\sigma_i\rangle=\vert 0\rangle,\,\vert 1\rangle\dots\vert Q-1\rangle` of dimension :math:`Q`.
If you think about spins: :math:`Q=2S+1` for :math:`S=\frac{1}{2},1,\frac{3}{2},\dots`



Basic structure
---------------



The :ref:`State` uses **bitwise** compressed storage of the state as an array of integers, **std::array<IntType,NInt>**, with a predefined number of used integers **NInt**, and predefined integer type, **IntType**.
This is the *only* data field.
The local state :math:`\vert\sigma_i\rangle` of site :math:`i` is represented using **Nbits** bits.  There are two important **template parameters** that have to be adjusted:

* **uint64_t MaxSites**: The maximal number of sites of the system (Default: 128)

* **uint64_t Q**: The dimension of the local Hilbert space, :math:`Q` (Default: 2)


Further template parameters are **class IntType** that defines the primitive integer used by **std::array** (Default: **uint64_t**), **uint64_t Nbits** defines the number of bits necessary to encode a single qudit :math:`\vert\sigma_i\rangle` (Default: minimal number required by **Q**), and **uint64_t NInt** which is the length of the array (Default: minimal number required by **Nbits** and **MaxSites**).


Basic usage
-----------



**using** enables an easy handling of the class within its namespace **state_space**:


.. code-block:: cpp
   :linenos:

    /* Defining the State with std::array<uint64_t, 8> */
    using danceq::internal::State<256,4>;  // MaxSites=256, Q=4

    /* Default constructor which initiates all sites with zeros: |0> */
    State state; 


In that case, :ref:`State` encodes up to 256 qudits with a local Hilbert space dimension of 4 using an array of **uint64_t** of length *8*: **std::array<uint64_t, 8>**


The :ref:`State` class provides simple read and write functions to target individual sites:

.. code-block:: cpp
   :linenos:

    /* Reading site 100 which is |0> */
    auto local_state = state[100]; // 
    std::cout << "local_state = " << local_state << std::endl;

    /* Setting site 100 to |1> */
    state.set_state(1,100);

    /* Reading site 100 which is |1> */
    local_state = state[100]; 
    std::cout << "local_state = " << local_state << std::endl;



Fixing the array length allows not only high-performance computations but also an easy handling using `MPI <https://de.wikipedia.org/wiki/Message_Passing_Interface>`_.
A **MPI_Datatype** can be defined by:

.. code-block:: cpp
   :linenos:

    MPI_Datatype MPI_State;
    MPI_Type_contiguous(static_cast<int32_t>(State::template_struct::template_NInt), MPI_UNSIGNED_LONG, &MPI_State);
    MPI_Type_commit(&MPI_State);



Furthermore, the :ref:`State` class comes with a broad class of functions supporting the use of `ordered sets <https://en.cppreference.com/w/cpp/container/set>`_ , `ordered maps <https://en.cppreference.com/w/cpp/container/map>`_, `unordered sets <https://en.cppreference.com/w/cpp/container/unordered_set>`_ , and `unordered maps <https://en.cppreference.com/w/cpp/container/unordered_map>`_:


.. code-block:: cpp
   :linenos:

    std::set<State> mySet;
    std::map<State, uint64_t> myMap;
    std::unordered_set<State, typename State::HashFunction> myuSet;
    std::unordered_map<State, uint64_t, typename State::HashFunction> myuMap;




Detailed documentations
-----------------------



The most important constructors and functions are listed in :ref:`Constructors<State_Constructors>` and :ref:`Functions<State_Functions>`. Please follow the :ref:`Autodocs<State_Autodocs>` for the full documentation.






.. toctree::
    :maxdepth: 2
    :titlesonly:
 
    State/Members.rst
    State/Constructors.rst
    State/Functions.rst
    State/Autodocs.rst