qemcmc.sampler.runners

Classes

Runner	Base class for running MCMC routines.
MCMCRunner	Orchestrates a standard MCMC run loop.
ConstrainedMCMCRunner	Orchestrates an MCMC run that enforces a hard constraint.

Module Contents

class qemcmc.sampler.runners.Runner

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

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.

Parameters:

• energy_s (float) – Energy of the current state s.

• energy_sprime (float) – Energy of the proposed state s'.

• temperature (float, optional) – Temperature T, default is 1.0.

Returns:

The acceptance probability.

Return type:

float

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

Parameters:

• energy_s (float) – Energy of the current state s.

• energy_sprime (float) – Energy of the proposed state s’.

• temperature (float, optional) – Temperature T, default is 1.0.

Returns:

True if the new state is accepted, False otherwise.

Return type:

bool

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

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

Parameters:

• model (EnergyModel) – The energy model defining the system.

• temp (float) – The temperature for the Metropolis acceptance criterion.

model

temp

run(proposer: qemcmc.sampler.proposal.Proposal, n_hops: int, initial_state: str | None = None, name: str | None = None, verbose: bool = False, sample_frequency: int = 1) → qemcmc.utils.MCMCChain

Run the MCMC simulation.

Parameters:

• proposer (Proposal) – The proposal engine for generating new states.

• n_hops (int) – The number of MCMC steps to perform.

• initial_state (str, optional) – The starting bitstring for the chain. If None, a random state is generated.

• name (str, optional) – A name for the MCMC chain.

• verbose (bool, optional) – Enable progress bar and print statements.

• sample_frequency (int, optional) – The frequency at which to sample states for the chain. Default is 1 (every step).

Returns:

The generated Markov chain of states.

Return type:

MCMCChain

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

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

Parameters:

• model (ConstraintModel) – A model that includes a constraint function.

• temp (float) – The temperature for the Metropolis acceptance test.

• reject_invalid (bool, optional) – Proposed states that violate the constraint are rejected. Default is True.

model

temp

constraint_func

reject_invalid = True

uniform = False

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

Run the constrained MCMC simulation.

Parameters:

• proposer (Proposal) – The proposal engine for generating new states.

• n_hops (int) – The number of MCMC steps to perform.

• initial_state (str, optional) – The starting bitstring for the chain. Must satisfy the constraint. If None, a valid random state is sought. Default is None.

• name (str, optional) – A name for the MCMC chain. Default is None and later derived from the proposer method.

• verbose (bool, optional) – Enables progress bar and print statements. Default is False.

• sample_frequency (int, optional) – The frequency at which to sample states for the chain. Default is 1.

• return_rejections (bool, optional) – Return the number of rejections due to constraint violations. Default is True.

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.

Return type:

tuple[MCMCChain, int]