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

.. py:module:: qemcmc.utils.helpers


Classes
-------

.. autoapisummary::

   qemcmc.utils.helpers.MCMCState
   qemcmc.utils.helpers.MCMCChain
   qemcmc.utils.helpers.CoarseGrainingConfig


Functions
---------

.. autoapisummary::

   qemcmc.utils.helpers.plot_chains
   qemcmc.utils.helpers.get_random_state
   qemcmc.utils.helpers.get_all_possible_states
   qemcmc.utils.helpers.magnetization_of_state
   qemcmc.utils.helpers.dict_magnetization_of_all_states
   qemcmc.utils.helpers.hamming_dist
   qemcmc.utils.helpers.hamming_dist_related_counts
   qemcmc.utils.helpers.energy_difference_related_counts
   qemcmc.utils.helpers.validate_subgroups


Module 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:: magnetization_of_state(bitstring: str) -> float

   Parmeters:
       bitstring: for eg: '010'
   :returns: Magnetization for the given bitstring
   :rtype: float


.. py:function:: dict_magnetization_of_all_states(list_all_possible_states: list) -> dict

   Returns magnetization for all unique states

   :param list_all_possible_states:

   :returns: A dictionary mapping each state to its magnetization value.
   :rtype: dict


.. py:function:: hamming_dist(str1, str2)

.. py:function:: hamming_dist_related_counts(num_spins: int, sprime_each_iter: list, states_accepted_each_iter: list)

.. py:function:: energy_difference_related_counts(num_spins, sprime_each_iter: list, states_accepted_each_iter: list, model_in)

.. py:class:: CoarseGrainingConfig

   .. py:attribute:: subgroups
      :type:  list[list[int]]


   .. py:attribute:: subgroup_probs
      :type:  list[float]


.. 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: