.. _State_Conserve_Functions:

**********************************************
State enumeration **with** number conservation
**********************************************

All functions have the name tag **_conserve** which means that the total :ref:`particle number<eq:state_functions_particle_number>` is conserved.
The :ref:`particle number<eq:state_functions_particle_number>` within the range can be obtained by :ref:`get_particle_number(start,end)<State_Conserve_Functions_get_particle_number>`.
The number of possible states is given by :ref:`Eq. (2)<eq:dim>` which is returned by :ref:`get_dim_U1(...)<State_Conserve_Functions_get_dim_U1>`.
The :ref:`constructor<State_Index_Constructors_Conserve>` can be found in :ref:`Constructors with indexing<State_Index_Constructors>`.
We provide functions for :ref:`forward<State_Conserve_Functions_increment_U1>` and :ref:`backward<State_Conserve_Functions_decrement_U1>` iteration as well as mappings from :ref:`indices to the physical state<State_Conserve_Functions_set_state_from_index_U1>` and :ref:`vice versa<State_Conserve_Functions_get_index_U1>`.


*   **Example code**:

    .. code-block:: cpp

        using State = danceq::internal::State<5,4,uint64_t>;

        uint64_t start = 1;
        uint64_t end = 4;
        uint64_t number = 3;

        State state(0UL, number, start, end);
        uint64_t dim = state.get_dim_U1(number,end-start);
        std::cout << "[main] - dim  = " << dim << std::endl;

        for(uint64_t i = 0; i < dim; i++){
            std::cout << "[main] - |Psi_" << i << "> = " << state << std::endl;
            state.increment_U1(start,end);
        }

*   **Output**:

    .. code-block:: console

        [main] - dim = 10
        [main] - |Psi_0> = |0;3;0;0;0>
        [main] - |Psi_1> = |0;2;1;0;0>
        [main] - |Psi_2> = |0;1;2;0;0>
        [main] - |Psi_3> = |0;0;3;0;0>
        [main] - |Psi_4> = |0;2;0;1;0>
        [main] - |Psi_5> = |0;1;1;1;0>
        [main] - |Psi_6> = |0;0;2;1;0>
        [main] - |Psi_7> = |0;1;0;2;0>
        [main] - |Psi_8> = |0;0;1;2;0>
        [main] - |Psi_9> = |0;0;0;3;0>


.. _State_Conserve_Functions_get_particle_number:

.. doxygenfunction:: danceq::internal::State::get_particle_number(const uint64_t start = 0, const uint64_t end = MaxSites) const

.. _State_Conserve_Functions_get_dim_U1:

.. doxygenfunction:: danceq::internal::State:: get_dim_U1(const uint64_t number, const uint64_t length = MaxSites, const uint64_t Q_ = Q)


.. _State_Conserve_Functions_set_state_from_index_U1:

.. doxygenfunction:: danceq::internal::State::set_state_from_index_U1(const uint64_t index, const IntType num, const uint64_t start = 0, const uint64_t end = MaxSites)

.. _State_Conserve_Functions_get_index_U1:

.. doxygenfunction:: danceq::internal::State::get_index_U1(const uint64_t start = 0, const uint64_t end = MaxSites) const

.. _State_Conserve_Functions_increment_U1:

.. doxygenfunction:: danceq::internal::State:: increment_U1(uint64_t start = 0, uint64_t end = MaxSites, bool* overflow = nullptr)

.. _State_Conserve_Functions_decrement_U1:

.. doxygenfunction:: danceq::internal::State:: decrement_U1(uint64_t start = 0, uint64_t end = MaxSites, bool* overflow = nullptr)