qemcmc.sampler.qe_proposal

Attributes

DEFAULT_DELTA_T

Classes

QeProposal

Quantum-enhanced Markov Chain Monte Carlo sampler.

Module Contents

qemcmc.sampler.qe_proposal.DEFAULT_DELTA_T = 0.8

class qemcmc.sampler.qe_proposal.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].