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.

Link to GitHub repo: https://github.com/Stuartferguson00/QeMCMC

The implementation is inspired by the numerics in Layden et al's paper on QeMCMC and builds upon the foundations of the pafloxy/quMCMC repository.

Documentation

Documentation and examples can be found here.

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
• Hamiltonian Evolution: Build the corresponding quantum Hamiltonian based on the given couplings and run Trotterised time evolution with PennyLane's lightning qubit simulator
• Coarse Graining: Optionally use local updates on chosen subgroups of spins to scale proposals
• Constraining: Implementation of hard and soft constraints for a given model

Installation

Install the latest release from PyPI (requires Python 3.13+):

pip install qemcmc

From source

The example notebooks live in this repo, not the published package. To run them or to develop QeMCMC, clone the repo and install with uv:

cd QeMCMC
uv sync

uv sync creates a local environment .venv and installs the locked dependencies from pyproject.toml and uv.lock.

License

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

Authors

This project is maintained by Feroz Hassan & Stuart Ferguson.

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

• fhassan2@ed.ac.uk
• S.A.Ferguson-3@sms.ed.ac.uk.

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.