qemcmc.sampler.runners
======================

.. py:module:: qemcmc.sampler.runners


Classes
-------

.. autoapisummary::

   qemcmc.sampler.runners.Runner
   qemcmc.sampler.runners.MCMCRunner
   qemcmc.sampler.runners.ConstrainedMCMCRunner


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

.. py:class:: Runner

   Base class for running MCMC routines.
   Subclasses implement specific MCMC based algorithms.


   .. py:method:: get_acceptance_probability(energy_s: float, energy_sprime: float, temperature: float = 1.0) -> float

      Calculate the Metropolis acceptance probability.

      This computes exp(-(E(s') - E(s)) / T), used to determine the acceptance
      probability of a new state s' given the current state s.

      :param energy_s: Energy of the current state ``s``.
      :type energy_s: float
      :param energy_sprime: Energy of the proposed state ``s'``.
      :type energy_sprime: float
      :param temperature: Temperature T, default is ``1.0``.
      :type temperature: float, optional

      :returns: The acceptance probability.
      :rtype: float



   .. py:method:: is_accepted(energy_s: float, energy_sprime: float, temperature: float = 1.0) -> bool

      Decide whether to accept a proposed state.

      Accepts state s' with probability A = min(1, exp(-(E(s')-E(s))/T)).

      :param energy_s: Energy of the current state s.
      :type energy_s: float
      :param energy_sprime: Energy of the proposed state s'.
      :type energy_sprime: float
      :param temperature: Temperature T, default is ``1.0``.
      :type temperature: float, optional

      :returns: True if the new state is accepted, False otherwise.
      :rtype: bool



.. py:class:: MCMCRunner(model: qemcmc.model.EnergyModel, temp: float)

   Bases: :py:obj:`Runner`


   Orchestrates a standard MCMC run loop.

   This runner uses a given proposal sampler and energy model to generate a Markov chain
   of states. It manages state updates, energy evaluations, and Metropolis acceptance tests.
   The sampler targets the Boltzmann distribution p(s) ∝ exp(-E(s) / T).

   :param model: The energy model defining the system.
   :type model: EnergyModel
   :param temp: The temperature for the Metropolis acceptance criterion.
   :type temp: float


   .. py:attribute:: model


   .. py:attribute:: temp


   .. py:method:: run(proposer: qemcmc.sampler.proposal.Proposal, n_hops: int, initial_state: Optional[str] = None, name: Optional[str] = None, verbose: bool = False, sample_frequency: int = 1) -> qemcmc.utils.MCMCChain

      Run the MCMC simulation.

      :param proposer: The proposal engine for generating new states.
      :type proposer: Proposal
      :param n_hops: The number of MCMC steps to perform.
      :type n_hops: int
      :param initial_state: The starting bitstring for the chain. If None, a random state is generated.
      :type initial_state: str, optional
      :param name: A name for the MCMC chain.
      :type name: str, optional
      :param verbose: Enable progress bar and print statements.
      :type verbose: bool, optional
      :param sample_frequency: The frequency at which to sample states for the chain. Default is ``1`` (every step).
      :type sample_frequency: int, optional

      :returns: The generated Markov chain of states.
      :rtype: MCMCChain



.. py:class:: ConstrainedMCMCRunner(model: qemcmc.model.ConstraintModel, temp: float, reject_invalid: bool = True, uniform: bool = False)

   Bases: :py:obj:`Runner`


   Orchestrates an MCMC run that enforces a hard constraint.

   If a proposed state does not satisfy the constraint, it is immediately rejected
   without computing its energy or testing the Metropolis criterion.

   :param model: A model that includes a constraint function.
   :type model: ConstraintModel
   :param temp: The temperature for the Metropolis acceptance test.
   :type temp: float
   :param reject_invalid: Proposed states that violate the constraint are rejected. Default is ``True``.
   :type reject_invalid: bool, optional


   .. py:attribute:: model


   .. py:attribute:: temp


   .. py:attribute:: constraint_func


   .. py:attribute:: reject_invalid
      :value: True



   .. py:attribute:: uniform
      :value: False



   .. py:method:: run(proposer: qemcmc.sampler.proposal.Proposal, n_hops: int, initial_state: Optional[str] = None, name: Optional[str] = None, verbose: bool = False, sample_frequency: int = 1, return_rejections: bool = True) -> Tuple[qemcmc.utils.MCMCChain, int]

      Run the constrained MCMC simulation.

      :param proposer: The proposal engine for generating new states.
      :type proposer: Proposal
      :param n_hops: The number of MCMC steps to perform.
      :type n_hops: int
      :param initial_state: The starting bitstring for the chain. Must satisfy the constraint.
                            If None, a valid random state is sought. Default is ``None``.
      :type initial_state: str, optional
      :param name: A name for the MCMC chain. Default is ``None`` and later derived from the proposer method.
      :type name: str, optional
      :param verbose: Enables progress bar and print statements. Default is ``False``.
      :type verbose: bool, optional
      :param sample_frequency: The frequency at which to sample states for the chain. Default is ``1``.
      :type sample_frequency: int, optional
      :param return_rejections: Return the number of rejections due to constraint violations. Default is ``True``.
      :type return_rejections: bool, optional

      :returns: A tuple containing the generated Markov chain and the number of rejections due to constraints. If return_rejections is False, only the MCMCChain is returned.
      :rtype: tuple[MCMCChain, int]