qemcmc.utils
============

.. py:module:: qemcmc.utils


Submodules
----------

.. toctree::
   :maxdepth: 1

   /api/qemcmc/utils/helpers/index


Classes
-------

.. autoapisummary::

   qemcmc.utils.MCMCState
   qemcmc.utils.MCMCChain


Functions
---------

.. autoapisummary::

   qemcmc.utils.plot_chains
   qemcmc.utils.get_random_state
   qemcmc.utils.get_all_possible_states
   qemcmc.utils.validate_subgroups


Package Contents
----------------

.. py:class:: MCMCState

   Represents a single step in an MCMC trajectory.

   Stores the proposed configuration, whether it was accepted by the
   Metropolis rule, its energy, and the position of the step in the chain.


   .. py:attribute:: bitstring
      :type:  str


   .. py:attribute:: accepted
      :type:  bool


   .. py:attribute:: energy
      :type:  float
      :value: None



   .. py:attribute:: position
      :type:  int
      :value: None



.. py:class:: MCMCChain(states: Optional[List[MCMCState]] = None, name: Optional[str] = 'MCMC')

   Container for the sequence of states produced during an MCMC run.

   This class records all proposed states, tracks accepted configurations,
   and provides helper methods for extracting trajectories, energies, and
   empirical distributions from the Markov chain.


   .. py:attribute:: name
      :value: 'MCMC'



   .. py:method:: add_state(state: MCMCState)


   .. py:property:: states


   .. py:method:: get_accepted_energies()


   .. py:method:: get_current_energy_array()


   .. py:method:: get_pos_array()


   .. py:method:: get_current_state_array()


   .. py:method:: get_all_energies()


   .. py:property:: current_state


   .. py:property:: accepted_states
      :type: List[str]



   .. py:method:: get_list_markov_chain() -> List[str]


   .. py:method:: get_accepted_dict(normalize: bool = False, until_index: int = -1)


.. py:function:: plot_chains(chains: list[MCMCChain], color: str, label: str, plot_individual_chains: bool = True)

.. py:function:: get_random_state(num_spins: int) -> str

   Generate a random state for a given number of spins.

   :param num_spins: The number of spins in the system.
   :type num_spins: int

   :returns: A bitstring representing the random state.
   :rtype: str


.. py:function:: get_all_possible_states(num_spins: int) -> list

   Returns all possible binary strings of length n=num_spins

   Paremeters:
       num_spins: n length of the bitstring
   :returns: A list of all possible binary strings of length num_spins.
   :rtype: list


.. py:function:: validate_subgroups(subgroups, subgroup_probs, n_spins)

   Validate coarse-graining subgroups.

   Requirements:
     - subgroups is a non-empty list of non-empty sequences
     - each element is an int in [0, n-1]
     - each subgroup has no duplicate indices
     - every spin from 0 to n-1 appears in at least one subgroup

   :raises ValueError/TypeError: