qemcmc

Submodules

• qemcmc.circuits
• qemcmc.coarse_grain
• qemcmc.main
• qemcmc.model
• qemcmc.sampler
• qemcmc.spectralgap
• qemcmc.utils

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.
EnergyModel	A base class for energy models for a classical energy function over n spins,
ConstraintModel	A subclass of EnergyModel that incorporates a constraint function to define valid configurations.
ModelMaker	Utility class for constructing standard Ising energy models used in simulations and experiments.
CircuitMaker	Constructs and simulates quantum circuits used to generate QeMCMC proposals.
MCMCState	Represents a single step in an MCMC trajectory.
MCMCChain	Container for the sequence of states produced during an MCMC run.
SpectralGap	Class that finds the spectral gap, and the acceptance and proposal matrices for a given mcmc.
CoarseGraining	CoarseGraining class to generate partitions of spins for quantum proposals.

Functions

plot_chains(chains, color, label[, plot_individual_chains])
get_random_state(→ str)	Generate a random state for a given number of spins.
get_all_possible_states(→ list)	Returns all possible binary strings of length n=num_spins

Package Contents

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

class qemcmc.EnergyModel(n: int, couplings: List[numpy.ndarray] = [], name: str = None, cost_function_signs: list = [-1, -1], model_type: str = 'ising')

A base class for energy models for a classical energy function over n spins, defined by arbitrary-order coupling tensors.

Parameters:

• n – Number of spins

• couplings – List of numpy arrays representing interaction tensors. A 1D array encodes linear terms, a 2D array encodes pairwise terms (expected symmetric), and higher-rank tensors encode higher-order interactions.

• name – Optional label for the model (used in plotting / logging).

• cost_function_signs – Sign convention(s) used by downstream components (e.g. proposal/acceptance conventions). For example, [-1, -1] for linear and quadratic terms.

• model_type (str) – Type of model, either ‘ising’ or ‘binary’. This determines how the binary states are interpreted and how the energy is calculated. ‘ising’ models use spin values {-1, +1}, while ‘binary’ models use binary values {0, 1}.

Notes

• Energies are computed by mapping binary states {0,1} to spin values {-1,+1} internally.

• Brute-force methods such as get_all_energies scale as O(2^n) and are intended only for small systems.

n

n_spins

couplings = []

name = None

alphas

lowest_energy = None

normalised_couplings

cost_function_signs

initial_state = []

get_initial_states(num_initial_states: int)

Generates a list of random initial states.

Parameters:

num_initial_states – The number of initial states to generate.

Returns:

A list of random initial states.

Return type:

list

get_ground_state(num_reads=100, num_batches=10)

Finds an approximate ground state using Simulated Annealing.

calculate_energy(state, couplings, cost_function_signs)

Calculate the energy of a given state for an arbitrary-order Ising/binary model.

Parameters:

• state (array-like (str, list, tuple, np.array)) – State configuration. Can be: - Binary: “011”, [0,1,1], (0,1,1), etc. - Spin: [-1,1,1], (-1,1,1), etc.

• couplings (list of numpy arrays) – List of coupling tensors where: - 1D arrays represent linear terms (h_i) - 2D arrays represent quadratic terms (J_ij) - 3D arrays represent cubic terms, etc.

Returns:

float

Return type:

Total energy of the state

get_subgroup_couplings(subgroup: List[int], current_state: str, coupling_weights: List[float] = None)

Calculates local couplings for a subgroup of spins.

Spins outside the specified subgroup are treated as frozen constants, and their values are absorbed into the couplings of the subgroup. This is useful for calculating local effective Hamiltonians.

Parameters:

• subgroup (List[int]) – A list of indices of the spins in the subgroup.

• current_state (str) – The current state of the full system, as a binary string.

• coupling_weights (List[float], optional) – Optional weights for the couplings. This can be used to effectively remove certain couplings from the proposal (e.g., constraints) by setting their weight to 0. It is important not to normalize the couplings after applying these weights.

Returns:

A new list of coupling tensors for the subgroup.

Return type:

List[np.ndarray]

Notes

It might seem off to do the reweighting at this point, but here are reasons why I [SF] did it! Basically, when you get the subgroup couplings, the terms jumble up, so the returned local coupling list necessarily does not respect the order etc. of the different terms in the original.

calculate_alpha(n: int, couplings: list = None, eps: float = 1e-15) → numpy.ndarray

Compute alpha = sqrt(n) / sqrt(sum of squares of UNIQUE coupling coefficients), assuming coupling tensors are symmetric representations.

Any non-symmetric 2-body input raises ValueError.

Parameters:

• n (int) – Number of spins.

• couplings (list[np.ndarray], optional) – Couplings to use. Defaults to self.couplings if not provided.

• eps (float) – Small threshold to avoid division by zero.

Returns:

An array of normalising factors for each term in the couplings list.

Return type:

np.ndarray

get_energy(state: str) → float

Returns the energy of a given state

get_all_energies() → numpy.ndarray

Calculate the energies for all possible spin states. This method generates all possible spin states for the system and calculates the energy for each state.

Returns:

An array containing the energies of all possible spin states.

Return type:

np.ndarray

get_lowest_energies(num_states: int, return_configurations: bool = False) → Tuple[numpy.ndarray, numpy.ndarray]

Retrieve the lowest energy states and their degeneracies. This method computes all possible energies and then finds the specified number of lowest energy states along with their degeneracies.

Parameters:

• (int) (num_states)

• (bool) (return_configurations)

Returns:

• The first array contains the lowest energy values.

• The second array contains the degeneracies of the corresponding energy values.

Return type:

Tuple[np.ndarray, np.ndarray]

Notes

This method is intended for small instances due to its brute-force nature, which is extremely memory intensive and slow.

find_lowest_values(arr: numpy.ndarray, num_values: int = 5)

Find the lowest unique values in an array and their degeneracies.

Parameters:

• (np.ndarray) (arr)

• (int (num_values)

• optional) (The number of lowest unique values to find. Defaults to 5.)

Returns:

• lowest_values (np.ndarray): The lowest unique values in the array.

• degeneracy (np.ndarray): The counts of each of the lowest unique values.

Return type:

Tuple[lowest_values (np.ndarray), degeneracy (np.ndarray)]

get_lowest_energy()

Calculate and return the lowest energy from all possible energies. This method uses a brute force approach to find the lowest energy, making it extremely memory intensive and slow. It is recommended to use this method only for small instances.

Returns:

float

Return type:

The lowest energy value.

Notes

If the lowest energy has already been calculated and stored in self.lowest_energy, it will return that value directly to save computation time.

get_boltzmann_factor(state: str, beta: float = 1.0) → float

Get un-normalised boltzmann probability of a given state

Parameters:

• state (str) – configuration of spins for which probability is to be calculated

• beta (float) – inverse temperature (1/T) at which the probability is to be calculated.

Return type:

float corresponding to the un-normalised boltzmann probability of the given state.

get_boltzmann_factor_from_energy(E, beta: float = 1.0) → float

Get un-normalized Boltzmann probability for a given energy.

Parameters:

• E (float) – Energy for which the Boltzmann factor is to be calculated.

• beta (float) – Inverse temperature (1/T) at which the probability is to be calculated.

Returns:

The un-normalized Boltzmann probability for the given energy.

Return type:

float

class qemcmc.ConstraintModel(n: int, constraint_couplings: list[numpy.ndarray], constraint_signs: list[float], couplings: list[numpy.ndarray], constraint_func: Callable[[str], bool], **kwargs)

Bases: qemcmc.model.energy_model.EnergyModel

A subclass of EnergyModel that incorporates a constraint function to define valid configurations.

The constraint function takes a state as input and returns True if the state is valid (satisfies the constraint) and False otherwise. The energy of invalid states is set to infinity, effectively excluding them from the Boltzmann distribution.

Parameters:

• n (int) – Number of spins in the model.

• constraint_couplings (list[np.ndarray]) – List of coupling tensors (numpy arrays) defining the constraint.

• constraint_signs (list[float]) – Sign convention(s) for the constraint couplings.

• couplings (list[np.ndarray]) – List of coupling tensors (numpy arrays) defining the energy function.

• constraint_func (Callable[[str], bool]) – A function that takes a state (string representation of spin configuration) and returns True if the state satisfies the constraint, and False otherwise.

• name (str, optional) – Optional label for the model (used in plotting / logging).

• cost_function_signs (list[float], optional) – Sign convention(s) used by downstream components (e.g. proposal/acceptance conventions).

• model_type (str, optional) – Type of model, either ‘ising’ or ‘binary’. This determines how the binary states are interpreted and how the energy is calculated. ‘ising’ models use spin values {-1, +1}, while ‘binary’ models use binary values {0, 1}.

Notes

• The energy of any state that does not satisfy the constraint is set to infinity, which means such states will have zero probability in the Boltzmann distribution.

• This class can be used to model systems with hard constraints on the configurations, such as certain combinatorial optimization problems or physical systems with forbidden states.

constraint_func

get_initial_states

Generates a list of random initial states.

Parameters:

num_initial_states – The number of initial states to generate.

Returns:

A list of random initial states.

Return type:

list

constraint_couplings

constraint_signs

constraint_coupling_alphas

normalised_couplings

total_couplings

get_initial_states_constraint(num_initial_states: int)

Generates a list of random initial states that satisfy the constraint function.

Parameters:

num_initial_states – The number of initial states to generate.

Returns:

A list of random initial states that are valid according to the constraint.

Return type:

list

get_constraint_energy(state: str) → float

Calculate the energy contribution from the constraint couplings for a given state.

Parameters:

state (str) – The state for which to calculate the constraint energy.

Returns:

The energy contribution from the constraint couplings for the given state.

Return type:

float

get_total_energy(state: str) → float

Calculate the total energy of a given state, including both the regular energy and the constraint energy.

Parameters:

state (str) – The state for which to calculate the total energy.

Returns:

The total energy of the given state, including contributions from both the regular couplings and the constraint couplings.

Return type:

float

class qemcmc.ModelMaker(n_spins: int, model_type: str, name: str, cost_function_signs: list = [-1, -1])

Utility class for constructing standard Ising energy models used in simulations and experiments.

This class constructs predefined random energy models used for testing and experimentation. Depending on the chosen model_type, it generates coupling tensors and initialises an EnergyModel instance.

name

n_spins

cost_function_signs

make_fully_connected_ising()

make_fully_connected_binary()

Transforms the existing Ising couplings into an mathematically equivalent QUBO model via s = 2x - 1.

class qemcmc.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.

class qemcmc.MCMCState

Represents a single step in an MCMC trajectory.

Stores the proposed configuration, whether it was accepted by the Metropolis rule, its energy, and the position of the step in the chain.

bitstring: str

accepted: bool

energy: float = None

position: int = None

class qemcmc.MCMCChain(states: List[MCMCState] | None = None, name: str | None = 'MCMC')

Container for the sequence of states produced during an MCMC run.

This class records all proposed states, tracks accepted configurations, and provides helper methods for extracting trajectories, energies, and empirical distributions from the Markov chain.

name = 'MCMC'

add_state(state: MCMCState)

property states

get_accepted_energies()

get_current_energy_array()

get_pos_array()

get_current_state_array()

get_all_energies()

property current_state

property accepted_states: List[str]

get_list_markov_chain() → List[str]

get_accepted_dict(normalize: bool = False, until_index: int = -1)

qemcmc.plot_chains(chains: list[MCMCChain], color: str, label: str, plot_individual_chains: bool = True)

qemcmc.get_random_state(num_spins: int) → str

Generate a random state for a given number of spins.

Parameters:

num_spins (int) – The number of spins in the system.

Returns:

A bitstring representing the random state.

Return type:

str

qemcmc.get_all_possible_states(num_spins: int) → list

Returns all possible binary strings of length n=num_spins

Paremeters:

num_spins: n length of the bitstring

Returns:

A list of all possible binary strings of length num_spins.

Return type:

list

class qemcmc.SpectralGap(proposal: qemcmc.sampler.Proposal, model: qemcmc.model.energy_model.EnergyModel, temp: float = 1.0)

Bases: qemcmc.sampler.runners.Runner

Class that finds the spectral gap, and the acceptance and proposal matrices for a given mcmc.

proposal

model

temp = 1.0

find_acceptance_matrix()

Function to find the acceptance matrix for a given model instance.

Returns:

The acceptance matrix for the mcmc

Return type:

A (np.ndarray)

find_proposal_matrix_local()

Function to find the proposal matrix for a given local chain.

Returns:

The Q matrix for local proposal

Return type:

Q (np.ndarray)

find_proposal_matrix_uniform()

Function to find the proposal matrix for a given uniform chain.

Returns:

The Q matrix for uniform proposal

Return type:

Q (np.ndarray)

find_proposal_matrix_quantum()

Function to find the proposal matrix for a given QeMCMCChain object.

Returns:

The Q matrix for quantum proposal

Return type:

Q (np.ndarray)

find_proposal_matrix_brute_force(multiple=100)

find_proposal_matrix()

Function to find the proposal matrix for a given mcmc. This is not done by brute force

find_spectral_gap(A=None, Q=None)

Function to find the spectral gap of a given mcmc.

Parameters:

• (np.ndarray) (Q) – The acceptance matrix for the mcmc (optional, if not given, will be calculated)

• (np.ndarray) – The proposal matrix for the mcmc (optional, if not given, will be calculated)

class qemcmc.CoarseGraining(n, subgroups=None, subgroup_probs=None, repeated=True)

CoarseGraining class to generate partitions of spins for quantum proposals.

Parameters:

• n (int) – Number of spins in the system.

• subgroups (list[list[int]], optional) – A list of subgroups, where each subgroup is a list of spin indices. If None, the entire set of spins is treated as one subgroup.

• subgroup_probs (list[float], optional) – A list of probabilities corresponding to each subgroup, used for weighted random selection. Must sum to 1. If None, subgroups are selected uniformly at random.

• repeated (bool, optional) – If True, then multiple subgroups are run on the quantum computer in serial, if not then only one subgroup is selected at random and run on the quantum computer. Default is True.

_user_specified

n

subgroups = None

subgroup_probs = None

repeated = True

sample() → list[int]

Randomly samples a subgroup according to the specified probability distribution.

get_partitions(m: int) → list[list[int]]

Returns partitions of spins for sequential quantum updates.

If the user provided explicit subgroups at initialisation, those are returned directly (all if repeated=True, otherwise just the first). If no subgroups were specified, random disjoint partitions of approximate size n/m are generated.

Parameters:

m (int) – The number of partitions to generate. Ignored if user-specified subgroups are provided.