Quantum-enhanced Markov Chain Monte Carlo Simulator¶

This is a lightweight research package for Quantum-enhanced Markov Chain Monte Carlo (QeMCMC) sampling over discrete spin/bitstring configurations.

The implementation is inspired by the numerics in Layden’s work on QeMCMC and builds upon the foundations of the pafloxy/quMCMC repository.

Features¶

Arbitrary Energy Models: Define any classical Ising or QUBO-like model using a simple list of coupling tensors (example: 2D Ising h, J etc). A universal energy calculator handles arbitrary-order interactions
Automatic Hamiltonian Construction: Build the corresponding quantum Hamiltonian based on the given couplings and run Trotterised time evolution with PennyLane’s lightining qubit simulator
Coarse Graining: Optionally use local updates on chosen subgroups of spins to scale proposals
Constraining: Flexibly implementat of hard and soft constraints

Installation¶

This project uses uv, an extremely fast Python package installer written in Rust, intended as a drop-in replacement for pip and pip-tools. Official installation instructions available at astral.sh/uv

Install uv: For macOS and Linux run:

curl -LsSf https://astral.sh/uv/install.sh | sh

Create a virtual environment: From the project’s root directory, run:
```
uv sync
```
This will create a local .venv folder and install all required dependencies from pyproject.toml and uv.lock.

Quick Start¶

See notebooks\Basics\basic_QeMCMC.ipynb for an example MCMC on a fully connected Ising Model

1. Initialise an energy model¶

In this step, we define a classical energy function over binary spin configurations. This energy model is the target distribution that the QeMCMC sampler will explore.

from qemcmc.model import EnergyModel, ModelMaker
n = 10 # Number of spins in the system

# Build an Ising model to test the algorithms on
model_type = "Fully Connected Ising"
name = "Example Ising model"
model = ModelMaker(n, model_type, name).model

2. (Optional) Define coarse graining¶

Coarse graining allows the sampler to propose local multi-spin updates on predefined subgroups, rather than updating all spins at once.

from qemcmc.coarse_grain import CoarseGraining

cg = CoarseGraining(
    n=n,
    subgroups=[[0,1], [2,3,4], [1,3]],
    subgroup_probs=[0.3, 0.5, 0.2],
)

Each subgroup specifies a set of spin indices that may be updated together. At each MCMC step, a subgroup is sampled according to subgroup_probs.

3. Create and run QeMCMC¶

Finally, we initialise the quantum-enhanced Markov chain and generate a single proposal using simulated quantum time evolution.

from qemcmc.sampler import QeProposal
from qemcmc.sampler.runners import MCMCRunner
reps = 5 # How many markov chains to produce
steps = 300 # Length of each markov chain
temp = 0.1 # Temperature of the system


# Define your MCMC algorithm runner
runner = MCMCRunner(model, temp)

# Define Quantum parameters
gamma = (0.3,0.6)# Relative strength of mixer hamiltonian 
time = (1,10) # Time for hamiltonian simulation

# Define your quantum proposal
quantum_proposal = QeProposal(model, gamma=gamma, time=time)

# Run the sampler
runner.run(quantum_proposal, steps, name="QeMCMC", verbose=True)

Coarse Graining¶

To do coarse graining, a list of subgroups and it’s corresponding probabilities along with the couplings list should be passed in as parameters when initializing a coarse graining object. The subgroup list should contain lists of spin indices that belong to each subgroup. For example, for a system with 6 spins divided into 2 subgroups of 3 spins each, the subgroup list would be [[0, 1, 2], [3, 4, 5]].

NOTE: All spins must belong to at least one subgroup and subgroups may overlap (i.e., a spin may belong to multiple subgroups).

The CircuitMaker will then automatically build the evolution circuit to perform coarse graining based on these subgroups.

Documentation¶

QeMCMC’s documentation is available at docs.

License¶

Distributed under the MIT License. See LICENSE for more information.

Authors¶

This project was created by Stuart Ferguson and maintained by Feroz Hassan.

For questions, suggestions, or collaboration, please feel free to contact the authors:

Acknowledgements¶

pafloxy/quMCMC for the foundational code.
Quantum-enhanced Markov Chain Monte Carlo by David Layden et al.
Quantum-enhanced MCMC for systems larger than your Quantum Computer by S. Ferguson and P. Wallden.

Getting Started

Usage

Example 2D Ising Model

Package API Docs

API Reference
- qemcmc

Development