.. _Container:

#########
Container
#########

The purpose of the :ref:`Container class<Container>` is the enumeration of an individual subsystems of length :math:`L_P`.
It uniquely maps a truncated :ref:`states<State>`, :math:`\vert\Psi_P\rangle`, with a fixed particle number :math:`n_P` between **start** and **end** to an index within :math:`0` and :math:`D_Q(L_P,n_p)`.
Here, :math:`D_Q(...)` refers to the :ref:`dimensional formula<eq:dim>` and determines the number of possible states with a local Hilbert space dimension :math:`Q`, length :math:`L_P`, and particle number :math:`n_P`.
The particle number :math:`n_P` ranges from :math:`0` to :math:`\max \left(L_P\cdot(Q-1),n\right)` where :math:`n` is the total particle number of the entire system.

Let's illustrate that on an example for :math:`L_P=3`, :math:`Q=3`, and :math:`n_P\in[0,6]`:

* Mapping for :math:`n_P=0` - :math:`D_3(3,0)=1`:

    +--------------------------------------+
    | :math:`\vert 0;0;0\rangle  \mapsto 0`|
    +--------------------------------------+

* Mapping for :math:`n_P=1` - :math:`D_3(3,1)=3`:

    +--------------------------------------+--------------------------------------+--------------------------------------+
    | :math:`\vert 0;0;1\rangle  \mapsto 0`| :math:`\vert 0;1;0\rangle  \mapsto 1`| :math:`\vert 1;0;0\rangle  \mapsto 2`|
    +--------------------------------------+--------------------------------------+--------------------------------------+

* Mapping for :math:`n_P=2` - :math:`D_3(3,2)=6`:

    +--------------------------------------+--------------------------------------+--------------------------------------+--------------------------------------+--------------------------------------+--------------------------------------+
    | :math:`\vert 0;0;2\rangle  \mapsto 0`| :math:`\vert 0;1;1\rangle  \mapsto 1`| :math:`\vert 0;2;0\rangle  \mapsto 2`| :math:`\vert 1;0;1\rangle  \mapsto 3`| :math:`\vert 1;1;0\rangle  \mapsto 4`| :math:`\vert 2;0;0\rangle  \mapsto 5`|
    +--------------------------------------+--------------------------------------+--------------------------------------+--------------------------------------+--------------------------------------+--------------------------------------+

* Mapping for :math:`n_P=3` - :math:`D_3(3,4)=7`:

    +--------------------------------------+--------------------------------------+--------------------------------------+--------------------------------------+--------------------------------------+--------------------------------------+--------------------------------------+
    | :math:`\vert 0;1;2\rangle  \mapsto 0`| :math:`\vert 0;2;1\rangle  \mapsto 1`| :math:`\vert 1;0;2\rangle  \mapsto 2`| :math:`\vert 1;1;1\rangle  \mapsto 3`| :math:`\vert 1;2;0\rangle  \mapsto 4`| :math:`\vert 2;0;1\rangle  \mapsto 5`| :math:`\vert 2;1;1\rangle  \mapsto 6`|
    +--------------------------------------+--------------------------------------+--------------------------------------+--------------------------------------+--------------------------------------+--------------------------------------+--------------------------------------+

* Mapping for :math:`n_P=4` - :math:`D_3(3,4)=6`:

    +--------------------------------------+--------------------------------------+--------------------------------------+--------------------------------------+--------------------------------------+--------------------------------------+
    | :math:`\vert 0;2;2\rangle  \mapsto 0`| :math:`\vert 1;1;2\rangle  \mapsto 1`| :math:`\vert 1;2;1\rangle  \mapsto 2`| :math:`\vert 2;0;2\rangle  \mapsto 3`| :math:`\vert 2;1;1\rangle  \mapsto 4`| :math:`\vert 2;2;0\rangle  \mapsto 5`|
    +--------------------------------------+--------------------------------------+--------------------------------------+--------------------------------------+--------------------------------------+--------------------------------------+

* Mapping for :math:`n_P=5` - :math:`D_3(3,5)=3`:

    +--------------------------------------+--------------------------------------+--------------------------------------+
    | :math:`\vert 1;2;2\rangle  \mapsto 0`| :math:`\vert 2;1;2\rangle  \mapsto 1`| :math:`\vert 2;2;1\rangle  \mapsto 2`|
    +--------------------------------------+--------------------------------------+--------------------------------------+


* Mapping for :math:`n_P=6` - :math:`D_3(3,5)=1`:

    +--------------------------------------+
    | :math:`\vert 2;2;2\rangle  \mapsto 0`|
    +--------------------------------------+


.. note::
   
    * The precise order of :ref:`states<State>` does not matter as long as it is unique within :math:`0` and :math:`D_Q(L_P,n_P)`.

    * Subsystems of the same length use the same :ref:`Container<Container>` instance to reduce the memory usage.


There are three different implementations of the :ref:`Container class<Container>` that use different approaches to organize the subsystem but provide the same functionality:

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

    Container/ContainerTable.rst
    Container/ContainerDict.rst
    Container/ContainerFly.rst

Advantages and disadvantages are discussed in detail in the :ref:`paper<Paper>`.
The use of lookup-tables is the original proposal of :footcite:t:`lin_exact_1990` generalized to arbitrary :math:`Q` and an arbitrary number of subsystems.
In addition, we provide a dictionary for the lookup which is less memory consuming for a small number of particles.
On top of that, we provide an **on-the-fly** implementation without any notable memory overhead.



All implementations have the same functionality and are exchangeable.
The basic ideas and data members are introduced in :ref:`Container Table<ContainerTable>`, :ref:`Container Dictionary<ContainerDict>`, and :ref:`Container on-the-fly<ContainerFly>`.
We list more detailed documentation for the :ref:`Constructors<Container_Constructors>` and :ref:`Functions<Container_Functions>` for the :ref:`Container Table<ContainerTable>` instance.
Other implementations are equivalent.

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

    Container/Constructors.rst
    Container/Functions.rst


The full documentations for all options are listed here: :ref:`Autodocs - Container Table<Autodocs_ContainerTable>`, :ref:`Autodocs - Container Dictionary<Autodocs_ContainerDict>`, and :ref:`Autodocs - Container on-the-fly<Autodocs_ContainerFly>`.
 

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

    Container/Autodocs_Table.rst
    Container/Autodocs_Dict.rst
    Container/Autodocs_Fly.rst


.. footbibliography::