qemcmc.sampler

Submodules

• qemcmc.sampler.classical_proposal
• qemcmc.sampler.proposal
• qemcmc.sampler.qe_proposal
• qemcmc.sampler.runners

Classes

Proposal	Abstract base class for producing proposals for Markov Chain Monte Carlo algorithms.
ClassicalProposal	Classical Markov Chain Monte Carlo proposer.
QeProposal	Quantum-enhanced Markov Chain Monte Carlo sampler.

Package Contents

class qemcmc.sampler.Proposal(model: qemcmc.model.EnergyModel)

Bases: abc.ABC

Abstract base class for producing proposals for Markov Chain Monte Carlo algorithms.

Subclasses implement the proposal mechanism by defining an update(state) method that generates a candidate state from the current one (e.g. single-spin flips, block updates, or quantum proposals).

Parameters:

model (EnergyModel) – Energy model defining the target distribution over spin configurations.

model

n_spins

abstractmethod update(state: qemcmc.utils.MCMCState) → qemcmc.utils.MCMCState

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

Parameters:

state (MCMCState) – The current state of the Markov chain.

Returns:

A new candidate state.

Return type:

MCMCState

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

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

Parameters:

• model (EnergyModel) – Energy model defining the target Boltzmann distribution.

• method (str, optional) –

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

METHODS

method = 'uniform'

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

Parameters:

state (MCMCState) – The current state of the Markov chain.

Returns:

A new candidate state.

Return type:

MCMCState

update_uniform(current_state_bitstring: str) → str

Proposes a new state by generating a random bitstring.

Parameters:

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

Returns:

A new random state bitstring of the same length.

Return type:

str

update_local(current_state_bitstring: str) → str

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

Parameters:

current_state_bitstring (str) – The current state represented as a bitstring.

Returns:

The new state bitstring after flipping one spin.

Return type:

str

update_2local(current_state_bitstring: str) → str

Proposes a new state by flipping two randomly chosen spins.

Parameters:

current_state_bitstring (str) – The current state represented as a bitstring.

Returns:

The new state bitstring after flipping two spins.

Return type:

str

class qemcmc.sampler.QeProposal(model: qemcmc.model.EnergyModel, gamma: float | tuple[float, float], time: float | tuple[float, float], r: int | None = None, delta_t: float | None = None, coarse_graining: qemcmc.coarse_grain.CoarseGraining | None = None, coupling_weights: list[float | tuple[float, float]] | None = None, m: int = 1)

Bases: qemcmc.sampler.Proposal

Quantum-enhanced Markov Chain Monte Carlo sampler.

This class implements the proposal mechanism of the quantum-enhanced MCMC algorithm. Candidate states are generated by simulating the quantum time evolution of a transverse-field Hamiltonian.

The quantum proposal circuit is constructed using CircuitMaker and can optionally operate on coarse-grained subgroups of spins to improve scalability.

Parameters:

• model (EnergyModel) – Energy model defining the target Boltzmann distribution.

• gamma (float | tuple[float, float]) – Transverse field strength (Γ). If a tuple is provided, a value is sampled uniformly from the range [min, max] at each step.

• time (float | tuple[float, float]) – Total evolution time. If a tuple is provided, a value is sampled uniformly from the range [min, max] at each step.

• r (int | None, optional) – Number of Trotter steps. Mutually exclusive with delta_t. If provided, the Trotter step size is derived as Δt = t / r and r stays fixed while Δt varies with t. A warning is issued at init if the resulting Δt range falls outside [0.1, 2.0]. By default None.

• delta_t (float | None, optional) – Trotter step size. Mutually exclusive with r. If provided, the number of Trotter steps is derived as r = floor(t / Δt) per step, so r varies with t while Δt stays fixed. A warning is issued if Δt falls outside [0.1, 2.0]. By default None.

• coarse_graining (CoarseGraining | None, optional) – A coarse-graining scheme to define spin subgroups. If None, no coarse-graining is used. By default None.

• coupling_weights (list[float | tuple[float, float]] | None, optional) – Weights for the coupling tensors. If a tuple is provided, a weight is sampled uniformly from the range. This allows for dynamic adjustment of the influence of different terms in the Hamiltonian during the proposal step. By default None. Note that this is further adjusted by (1 - gamma) to balance the influence of the problem Hamiltonian with the mixer term. Divide by (1 - gamma) if needed. Also, note that the coupling weights should include the mixing term.

• m (int, optional) – Number of subgroups to partition the spins into for sequential updates. By default 1.

Notes

The proposal step simulates the time evolution under a transverse-field Hamiltonian defined by the energy model and measures the resulting state to produce a candidate configuration. This proposal is then accepted or rejected using the Metropolis criterion to ensure convergence to the target Boltzmann distribution.

Exactly one of r or delta_t should be passed in as an argument. If neither is given, a default Δt of 0.8 is used.

gamma

time

r = None

delta_t = None

m = 1

method = 'quantum'

CM

cg

update(current_state: str) → str

Perform ‘m’ sequential quantum updates across non-overlapping subgroups.

Parameters:

current_state (str) – Current state of the system as a bitstring.

Returns:

Updated state of the system as a bitstring.

Return type:

str

sample_hyperparams() → tuple[list[float], float, float, int]

Sample hyperparameters (coupling weights, gamma, time, r) for the current proposal step.

Returns:

(final_coupling_weights, gamma, time, r) for this proposal step.

Return type:

tuple[list[float], float, float, int]

_validate_gamma(gamma: float | tuple[float, float]) → float | tuple[float, float]

Validate the weight parameter gamma.

_validate_time(time: float | tuple[float, float]) → float | tuple[float, float]

Validate the total evolution time parameter.

_validate_r(r: int | None) → int | None

Validate the number of Trotter steps ‘r’.

_validate_delta_t(delta_t: float | None) → float | None

Validate the Trotter step size ‘delta_t’.

_validate_trotter_params()

Check mutual exclusivity of r and delta_t, and warn if resulting Trotter step size falls outside [0.1, 2.0].