qemcmc.circuits

Classes

CircuitMaker

Constructs and simulates quantum circuits used to generate QeMCMC proposals.

Module Contents

class qemcmc.circuits.CircuitMaker(model: qemcmc.model.energy_model.EnergyModel)

Constructs and simulates quantum circuits used to generate QeMCMC proposals.

This class builds the Hamiltonian corresponding to a given energy model and simulates its time evolution using PennyLane. Starting from a classical bitstring configuration, the circuit performs Trotterised quantum evolution and samples a new configuration from the resulting quantum state.

The generated sample serves as the proposal state in the quantum-enhanced MCMC algorithm.

Parameters:

model (EnergyModel) – Energy model defining the problem Hamiltonian.

Notes

The total Hamiltonian simulated by the circuit is

H = γ H_mixer + (1 - γ) α H_problem

where H_problem encodes the classical energy model and H_mixer corresponds to a transverse-field term. The evolution time t and number of Trotter steps r are passed per call, giving an effective Trotter step size of δt = t / r. The evolution is approximated using Trotterisation via qml.ApproxTimeEvolution.

model

n_qubits

dev

model_type

devices

_get_device(num_wires: int)

Get or create a PennyLane device for the given number of wires.

get_problem_hamiltonian(couplings: List[numpy.ndarray], sign: int = 1) → pennylane.Hamiltonian

Construct the problem Hamiltonian from symmetric coupling tensors.

This method supports both ‘ising’ (-1/+1) and ‘binary’ (0/1) models.

Parameters:

• couplings (List[np.ndarray]) – A list of coupling tensors.

• sign (int, optional) – A sign to apply to the Hamiltonian. Default is 1.

Returns:

The problem Hamiltonian.

Return type:

qml.Hamiltonian

get_mixer_hamiltonian(num_wires: int = None) → pennylane.Hamiltonian

Constructs the Mixer Hamiltonian: Σ X_i.

This can be for the full system or a subgroup.

Parameters:

num_wires (int, optional) – The number of wires (qubits) for the mixer. If None, uses the total number of qubits.

Returns:

The mixer Hamiltonian.

Return type:

qml.Hamiltonian

get_state_vector(s: str, weights: List[float], time: float, r: int, mix_weight: float) → numpy.ndarray

Evolve the initial state and return the final state vector.

Parameters:

• s (str) – Input bitstring representing the initial state.

• weights (list of float) – Coefficients for the problem Hamiltonian terms.

• time (float) – Total evolution time.

• r (int) – Number of Trotter steps for the approximate time evolution.

• mix_weight (float) – Coefficient for the mixer Hamiltonian (between 0 and 1).

Returns:

The final state vector.

Return type:

np.ndarray

Notes

The total Hamiltonian simulated by the circuit is a weighted sum of the problem Hamiltonian terms and the mixer Hamiltonian:

In Ferguson et al. (2025) [arXiv:2506.19538], we use gammas to weight the entire problem Hamiltonian vs the mixer vs the constraint Hamiltonian, such that the total Hamiltonian is:

H = g_p * H_p + g_m * H_m + g_c * H_c

but here we allow for separate weights for each coupling tensor term, as well as a separate gamma for the mixer. The total Hamiltonian is then:

H = (w_b1*H_b1 + w_b2*H_b2 + ... + w_b2*H_bm) + g_m * H_m

In other words, the constraint hamiltonian is absorbed in the coupling list, and weighted by the corresponding gamma in the gammas list. This allows for more flexible weighting of different terms, and also allows us to use the same code for both constrained and unconstrained problems (by simply including or excluding the constraint Hamiltonian in the coupling list and adjusting the gammas accordingly).

Note that it is assumed that each term is already normalised appropriately, so the gammas can be interpreted as the relative weights of each term in the total Hamiltonian.

get_sample(s_cg: str, time: float, r: int, mix_weight: float, local_couplings: list, weights: List[float] = None) → str

Generate a single sample by evolving the system and measuring.

Parameters:

• s_cg (str) – Input bitstring for the subgroup.

• time (float) – Total evolution time.

• r (int) – Number of Trotter steps for the approximate time evolution.

• mix_weight (float) – Coefficient for the mixer Hamiltonian.

• local_couplings (list) – Coupling tensors for the subgroup.

• weights (list of float, optional) – Coefficients for the problem Hamiltonian terms. Defaults to ones.

Returns:

A single bitstring sample.

Return type:

str

update(s: str, subgroup_choice: List[int], local_couplings: list, gamma: float, time: float, r: int) → str

Update a bitstring by evolving a subgroup.

This performs a time evolution on a coarse-grained Hamiltonian to get s’ from s.

Parameters:

• s (str) – The initial bitstring.

• subgroup_choice (list of int) – Indices of the subgroup to evolve.

• local_couplings (list) – Coupling tensors for the subgroup.

• gamma (float) – Mixing parameter.

• time (float) – Evolution time.

• r (int) – Number of Trotter steps for the approximate time evolution.

Returns:

The updated bitstring s’.

Return type:

str

_validate_bitstring(s: str, *, length: int = None)

Validate s is a bitstring.

Parameters:

• s (str) – The string to validate.

• length (int, optional) – The expected length of the string.

Raises:

• TypeError – If s is not a string.

• ValueError – If s contains characters other than ‘0’ or ‘1’, or if its length is wrong.