qemcmc.sampler.classical_proposal
=================================

.. py:module:: qemcmc.sampler.classical_proposal


Classes
-------

.. autoapisummary::

   qemcmc.sampler.classical_proposal.ClassicalProposal


Module Contents
---------------

.. py:class:: ClassicalProposal(model: qemcmc.model.EnergyModel, method: str = 'uniform')

   Bases: :py:obj:`qemcmc.sampler.Proposal`


   Classical Markov Chain Monte Carlo proposer.

   This class implements purely classical proposal mechanisms for MCMC.
   New candidate states are generated either by sampling a completely
   random (uniform) configuration, or by performing a local single-spin or
   two-spin flip.

   :param model: Energy model defining the target Boltzmann distribution.
   :type model: EnergyModel
   :param method: Proposal mechanism used to generate candidate states.

                  - ``"uniform"`` : propose a completely random spin configuration.
                  - ``"local"`` : flip a single randomly chosen spin.
                  - ``"2-local"`` : flip two randomly chosen spins.

                  Default is ``"uniform"``.
   :type method: str, optional


   .. py:attribute:: METHODS


   .. py:attribute:: method
      :value: 'uniform'



   .. py:method:: update(current_state_bitstring: str) -> str

      Generate a candidate state from the current state using the proposal mechanism.

      This method should be implemented by subclasses to define the specific proposal strategy
      (e.g., single-spin flips, block updates, or quantum proposals).

      :param state: The current state of the Markov chain.
      :type state: MCMCState

      :returns: A new candidate state.
      :rtype: MCMCState



   .. py:method:: update_uniform(current_state_bitstring: str) -> str

      Proposes a new state by generating a random bitstring.

      :param current_state_bitstring: The current state represented as a bitstring (not used, but required by the API).
      :type current_state_bitstring: str

      :returns: A new random state bitstring of the same length.
      :rtype: str



   .. py:method:: update_local(current_state_bitstring: str) -> str

      Proposes a new state by flipping a single randomly chosen spin.

      :param current_state_bitstring: The current state represented as a bitstring.
      :type current_state_bitstring: str

      :returns: The new state bitstring after flipping one spin.
      :rtype: str



   .. py:method:: update_2local(current_state_bitstring: str) -> str

      Proposes a new state by flipping two randomly chosen spins.

      :param current_state_bitstring: The current state represented as a bitstring.
      :type current_state_bitstring: str

      :returns: The new state bitstring after flipping two spins.
      :rtype: str