qemcmc 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- qemcmc-0.1.0/.github/workflows/docs.yaml +50 -0
- qemcmc-0.1.0/.github/workflows/publish.yaml +34 -0
- qemcmc-0.1.0/.gitignore +175 -0
- qemcmc-0.1.0/.python-version +1 -0
- qemcmc-0.1.0/LICENSE +21 -0
- qemcmc-0.1.0/PKG-INFO +169 -0
- qemcmc-0.1.0/README.md +145 -0
- qemcmc-0.1.0/docs/Makefile +20 -0
- qemcmc-0.1.0/docs/make.bat +35 -0
- qemcmc-0.1.0/docs/requirements.txt +45 -0
- qemcmc-0.1.0/docs/source/_static/logo-qsl.jpeg +0 -0
- qemcmc-0.1.0/docs/source/api.md +7 -0
- qemcmc-0.1.0/docs/source/authors.md +9 -0
- qemcmc-0.1.0/docs/source/coarse-graining.md +21 -0
- qemcmc-0.1.0/docs/source/conf.py +115 -0
- qemcmc-0.1.0/docs/source/energy-model.md +14 -0
- qemcmc-0.1.0/docs/source/example.md +63 -0
- qemcmc-0.1.0/docs/source/getting-started.md +16 -0
- qemcmc-0.1.0/docs/source/github.md +3 -0
- qemcmc-0.1.0/docs/source/index.md +38 -0
- qemcmc-0.1.0/docs/source/license.md +24 -0
- qemcmc-0.1.0/logo-qsl.jpeg +0 -0
- qemcmc-0.1.0/notebooks/H_E_graphs.py +168 -0
- qemcmc-0.1.0/notebooks/H_E_graphs_stu.py +209 -0
- qemcmc-0.1.0/notebooks/test.ipynb +263 -0
- qemcmc-0.1.0/notebooks/test.py +97 -0
- qemcmc-0.1.0/notebooks/tutorial.ipynb +462 -0
- qemcmc-0.1.0/pyproject.toml +36 -0
- qemcmc-0.1.0/setup.cfg +4 -0
- qemcmc-0.1.0/src/qemcmc/__init__.py +25 -0
- qemcmc-0.1.0/src/qemcmc/circuits.py +180 -0
- qemcmc-0.1.0/src/qemcmc/coarse_grain.py +28 -0
- qemcmc-0.1.0/src/qemcmc/main.py +78 -0
- qemcmc-0.1.0/src/qemcmc/model/__init__.py +4 -0
- qemcmc-0.1.0/src/qemcmc/model/energy_model.py +328 -0
- qemcmc-0.1.0/src/qemcmc/sampler/__init__.py +6 -0
- qemcmc-0.1.0/src/qemcmc/sampler/classical_mcmc.py +82 -0
- qemcmc-0.1.0/src/qemcmc/sampler/mcmc.py +162 -0
- qemcmc-0.1.0/src/qemcmc/sampler/qe_mcmc.py +150 -0
- qemcmc-0.1.0/src/qemcmc/spectralgap.py +162 -0
- qemcmc-0.1.0/src/qemcmc/utils/__init__.py +13 -0
- qemcmc-0.1.0/src/qemcmc/utils/helpers.py +308 -0
- qemcmc-0.1.0/src/qemcmc/utils/model_maker.py +62 -0
- qemcmc-0.1.0/src/qemcmc.egg-info/PKG-INFO +169 -0
- qemcmc-0.1.0/src/qemcmc.egg-info/SOURCES.txt +49 -0
- qemcmc-0.1.0/src/qemcmc.egg-info/dependency_links.txt +1 -0
- qemcmc-0.1.0/src/qemcmc.egg-info/entry_points.txt +2 -0
- qemcmc-0.1.0/src/qemcmc.egg-info/requires.txt +13 -0
- qemcmc-0.1.0/src/qemcmc.egg-info/top_level.txt +1 -0
- qemcmc-0.1.0/uv.lock +1388 -0
- qemcmc-0.1.0/workflows/ci.yml +23 -0
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
name: Build & Deploy Docs
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [ main ]
|
|
6
|
+
workflow_dispatch:
|
|
7
|
+
|
|
8
|
+
permissions:
|
|
9
|
+
contents: read
|
|
10
|
+
pages: write
|
|
11
|
+
id-token: write
|
|
12
|
+
|
|
13
|
+
concurrency:
|
|
14
|
+
group: "pages"
|
|
15
|
+
cancel-in-progress: true
|
|
16
|
+
|
|
17
|
+
jobs:
|
|
18
|
+
build:
|
|
19
|
+
runs-on: ubuntu-latest
|
|
20
|
+
steps:
|
|
21
|
+
- uses: actions/checkout@v4
|
|
22
|
+
|
|
23
|
+
- uses: actions/setup-python@v5
|
|
24
|
+
with:
|
|
25
|
+
python-version: "3.12"
|
|
26
|
+
|
|
27
|
+
- name: Install docs dependencies
|
|
28
|
+
run: |
|
|
29
|
+
python -m pip install --upgrade pip
|
|
30
|
+
pip install -r docs/requirements.txt
|
|
31
|
+
|
|
32
|
+
- name: Build Sphinx HTML
|
|
33
|
+
run: |
|
|
34
|
+
python -m sphinx -b html docs/source docs/build/html
|
|
35
|
+
|
|
36
|
+
- name: Upload artifact
|
|
37
|
+
uses: actions/upload-pages-artifact@v3
|
|
38
|
+
with:
|
|
39
|
+
path: docs/build/html
|
|
40
|
+
|
|
41
|
+
deploy:
|
|
42
|
+
runs-on: ubuntu-latest
|
|
43
|
+
needs: build
|
|
44
|
+
environment:
|
|
45
|
+
name: github-pages
|
|
46
|
+
url: ${{ steps.deployment.outputs.page_url }}
|
|
47
|
+
steps:
|
|
48
|
+
- name: Deploy to GitHub Pages
|
|
49
|
+
id: deployment
|
|
50
|
+
uses: actions/deploy-pages@v4
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
name: Publish qemcmc to PyPI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
tags:
|
|
6
|
+
- "v*"
|
|
7
|
+
|
|
8
|
+
jobs:
|
|
9
|
+
publish:
|
|
10
|
+
runs-on: ubuntu-latest
|
|
11
|
+
|
|
12
|
+
environment:
|
|
13
|
+
name: pypi
|
|
14
|
+
|
|
15
|
+
permissions:
|
|
16
|
+
id-token: write # for trusted publishing
|
|
17
|
+
|
|
18
|
+
steps:
|
|
19
|
+
- uses: actions/checkout@v4
|
|
20
|
+
with:
|
|
21
|
+
fetch-depth: 0
|
|
22
|
+
|
|
23
|
+
- uses: actions/setup-python@v5
|
|
24
|
+
with:
|
|
25
|
+
python-version: "3.13"
|
|
26
|
+
|
|
27
|
+
- name: Install build tool
|
|
28
|
+
run: pip install build
|
|
29
|
+
|
|
30
|
+
- name: Build
|
|
31
|
+
run: python -m build
|
|
32
|
+
|
|
33
|
+
- name: Publish
|
|
34
|
+
uses: pypa/gh-action-pypi-publish@release/v1
|
qemcmc-0.1.0/.gitignore
ADDED
|
@@ -0,0 +1,175 @@
|
|
|
1
|
+
# Byte-compiled / optimized / DLL files
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*$py.class
|
|
5
|
+
|
|
6
|
+
# C extensions
|
|
7
|
+
*.so
|
|
8
|
+
|
|
9
|
+
.gitignore
|
|
10
|
+
|
|
11
|
+
# Sphinx documentation
|
|
12
|
+
docs/doctrees/
|
|
13
|
+
docs/build/
|
|
14
|
+
|
|
15
|
+
# figures
|
|
16
|
+
plots
|
|
17
|
+
|
|
18
|
+
# Distribution / packaging
|
|
19
|
+
.Python
|
|
20
|
+
build/
|
|
21
|
+
develop-eggs/
|
|
22
|
+
dist/
|
|
23
|
+
downloads/
|
|
24
|
+
eggs/
|
|
25
|
+
.eggs/
|
|
26
|
+
lib/
|
|
27
|
+
lib64/
|
|
28
|
+
parts/
|
|
29
|
+
sdist/
|
|
30
|
+
var/
|
|
31
|
+
wheels/
|
|
32
|
+
share/python-wheels/
|
|
33
|
+
*.egg-info/
|
|
34
|
+
.installed.cfg
|
|
35
|
+
*.egg
|
|
36
|
+
MANIFEST
|
|
37
|
+
|
|
38
|
+
# PyInstaller
|
|
39
|
+
# Usually these files are written by a python script from a template
|
|
40
|
+
# before PyInstaller builds the exe, so as to inject date/other infos into it.
|
|
41
|
+
*.manifest
|
|
42
|
+
*.spec
|
|
43
|
+
|
|
44
|
+
# Installer logs
|
|
45
|
+
pip-log.txt
|
|
46
|
+
pip-delete-this-directory.txt
|
|
47
|
+
|
|
48
|
+
# Unit test / coverage reports
|
|
49
|
+
htmlcov/
|
|
50
|
+
.tox/
|
|
51
|
+
.nox/
|
|
52
|
+
.coverage
|
|
53
|
+
.coverage.*
|
|
54
|
+
.cache
|
|
55
|
+
nosetests.xml
|
|
56
|
+
coverage.xml
|
|
57
|
+
*.cover
|
|
58
|
+
*.py,cover
|
|
59
|
+
.hypothesis/
|
|
60
|
+
.pytest_cache/
|
|
61
|
+
cover/
|
|
62
|
+
|
|
63
|
+
# Translations
|
|
64
|
+
*.mo
|
|
65
|
+
*.pot
|
|
66
|
+
|
|
67
|
+
# Django stuff:
|
|
68
|
+
*.log
|
|
69
|
+
local_settings.py
|
|
70
|
+
db.sqlite3
|
|
71
|
+
db.sqlite3-journal
|
|
72
|
+
|
|
73
|
+
# Flask stuff:
|
|
74
|
+
instance/
|
|
75
|
+
.webassets-cache
|
|
76
|
+
|
|
77
|
+
# Scrapy stuff:
|
|
78
|
+
.scrapy
|
|
79
|
+
|
|
80
|
+
# Sphinx documentation
|
|
81
|
+
docs/_build/
|
|
82
|
+
|
|
83
|
+
# PyBuilder
|
|
84
|
+
.pybuilder/
|
|
85
|
+
target/
|
|
86
|
+
|
|
87
|
+
# Jupyter Notebook
|
|
88
|
+
.ipynb_checkpoints
|
|
89
|
+
|
|
90
|
+
# IPython
|
|
91
|
+
profile_default/
|
|
92
|
+
ipython_config.py
|
|
93
|
+
|
|
94
|
+
# pyenv
|
|
95
|
+
# For a library or package, you might want to ignore these files since the code is
|
|
96
|
+
# intended to run in multiple environments; otherwise, check them in:
|
|
97
|
+
# .python-version
|
|
98
|
+
|
|
99
|
+
# pipenv
|
|
100
|
+
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
|
|
101
|
+
# However, in case of collaboration, if having platform-specific dependencies or dependencies
|
|
102
|
+
# having no cross-platform support, pipenv may install dependencies that don't work, or not
|
|
103
|
+
# install all needed dependencies.
|
|
104
|
+
#Pipfile.lock
|
|
105
|
+
|
|
106
|
+
# poetry
|
|
107
|
+
# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
|
|
108
|
+
# This is especially recommended for binary packages to ensure reproducibility, and is more
|
|
109
|
+
# commonly ignored for libraries.
|
|
110
|
+
# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
|
|
111
|
+
#poetry.lock
|
|
112
|
+
|
|
113
|
+
# pdm
|
|
114
|
+
# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
|
|
115
|
+
#pdm.lock
|
|
116
|
+
# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
|
|
117
|
+
# in version control.
|
|
118
|
+
# https://pdm.fming.dev/latest/usage/project/#working-with-version-control
|
|
119
|
+
.pdm.toml
|
|
120
|
+
.pdm-python
|
|
121
|
+
.pdm-build/
|
|
122
|
+
|
|
123
|
+
# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
|
|
124
|
+
__pypackages__/
|
|
125
|
+
|
|
126
|
+
# Celery stuff
|
|
127
|
+
celerybeat-schedule
|
|
128
|
+
celerybeat.pid
|
|
129
|
+
|
|
130
|
+
# SageMath parsed files
|
|
131
|
+
*.sage.py
|
|
132
|
+
|
|
133
|
+
# Environments
|
|
134
|
+
.env
|
|
135
|
+
.venv
|
|
136
|
+
env/
|
|
137
|
+
venv/
|
|
138
|
+
ENV/
|
|
139
|
+
env.bak/
|
|
140
|
+
venv.bak/
|
|
141
|
+
|
|
142
|
+
# Spyder project settings
|
|
143
|
+
.spyderproject
|
|
144
|
+
.spyproject
|
|
145
|
+
|
|
146
|
+
# Rope project settings
|
|
147
|
+
.ropeproject
|
|
148
|
+
|
|
149
|
+
# mkdocs documentation
|
|
150
|
+
/site
|
|
151
|
+
|
|
152
|
+
# mypy
|
|
153
|
+
.mypy_cache/
|
|
154
|
+
.dmypy.json
|
|
155
|
+
dmypy.json
|
|
156
|
+
|
|
157
|
+
# Pyre type checker
|
|
158
|
+
.pyre/
|
|
159
|
+
|
|
160
|
+
# pytype static type analyzer
|
|
161
|
+
.pytype/
|
|
162
|
+
|
|
163
|
+
# Cython debug symbols
|
|
164
|
+
cython_debug/
|
|
165
|
+
|
|
166
|
+
# PyCharm
|
|
167
|
+
# JetBrains specific template is maintained in a separate JetBrains.gitignore that can
|
|
168
|
+
# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
|
|
169
|
+
# and can be added to the global gitignore or merged into this file. For a more nuclear
|
|
170
|
+
# option (not recommended) you can uncomment the following to ignore the entire idea folder.
|
|
171
|
+
#.idea/
|
|
172
|
+
|
|
173
|
+
# VS Code
|
|
174
|
+
.vscode/
|
|
175
|
+
.DS_Store
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
3.13
|
qemcmc-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024 Stuartferguson00, ferozmay
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
qemcmc-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: qemcmc
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Quantum enhanced Markov Chain Monte Carlo sampler simulated using PennyLane
|
|
5
|
+
Author: Stuart Ferguson, Feroz Hassan
|
|
6
|
+
License: MIT
|
|
7
|
+
Requires-Python: >=3.13
|
|
8
|
+
Description-Content-Type: text/markdown
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Requires-Dist: joblib>=1.5.0
|
|
11
|
+
Requires-Dist: matplotlib>=3.10.3
|
|
12
|
+
Requires-Dist: numpy<2.4,>=2.2.5
|
|
13
|
+
Requires-Dist: pandas>=2.2.3
|
|
14
|
+
Requires-Dist: pennylane==0.44
|
|
15
|
+
Requires-Dist: qiskit==2.2
|
|
16
|
+
Requires-Dist: qiskit-aer>=0.17.0
|
|
17
|
+
Requires-Dist: tqdm>=4.67.1
|
|
18
|
+
Requires-Dist: matplotlib-inline
|
|
19
|
+
Requires-Dist: ipykernel
|
|
20
|
+
Requires-Dist: iprogress
|
|
21
|
+
Requires-Dist: spyder-kernels==2.4
|
|
22
|
+
Requires-Dist: ipywidgets>=8.1.7
|
|
23
|
+
Dynamic: license-file
|
|
24
|
+
|
|
25
|
+
# Quantum-enhanced Markov Chain Monte Carlo Simulator
|
|
26
|
+
|
|
27
|
+
[](https://www.python.org/downloads/release/python-3130/)
|
|
28
|
+
[](https://quantum.cloud.ibm.com/docs/en/api/qiskit/release-notes/2.2)
|
|
29
|
+
[](https://docs.pennylane.ai/en/stable/)
|
|
30
|
+
[](https://opensource.org/licenses/MIT)
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
This is a lightweight research package for **Quantum-enhanced Markov Chain Monte Carlo** (QeMCMC) sampling over discrete spin/bitstring configurations.
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
The implementation is inspired by the numerics in [Layden's work on QeMCMC](https://www.nature.com/articles/s41586-023-06095-4) and builds upon the foundations of the [pafloxy/quMCMC](https://github.com/pafloxy/quMCMC) repository.
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
## Features
|
|
40
|
+
- **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
|
|
41
|
+
- **Automatic Hamiltonian Construction:** Build the corresponding **quantum Hamiltonian** based on the given couplings and run **Trotterised time evolution** with PennyLane's lightining qubit simulator
|
|
42
|
+
- **Coarse Graining**: Optionally use local updates on chosen subgroups of spins to scale proposals
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
## Installation
|
|
46
|
+
|
|
47
|
+
This project uses [`uv`](https://astral.sh/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](https://astral.sh/uv)
|
|
48
|
+
|
|
49
|
+
1. **Install `uv`:**
|
|
50
|
+
For macOS and Linux run:
|
|
51
|
+
```bash
|
|
52
|
+
curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
2. **Create a virtual environment:**
|
|
56
|
+
From the project's root directory, run:
|
|
57
|
+
```bash
|
|
58
|
+
uv sync
|
|
59
|
+
```
|
|
60
|
+
This will create a local `.venv` folder and install all required dependencies from `pyproject.toml` and `uv.lock`.
|
|
61
|
+
|
|
62
|
+
## Quick Start - Example 2D Ising Model
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
<!-- `model/energy_model.py`
|
|
66
|
+
|
|
67
|
+
```python
|
|
68
|
+
# Use our pre-defined base class to initialise an energy model
|
|
69
|
+
class EnergyModel():
|
|
70
|
+
...
|
|
71
|
+
|
|
72
|
+
# Or optionally define a problem specific energy model inheriting the base class EnergyModel
|
|
73
|
+
class your_energy_model(EnergyModel)
|
|
74
|
+
...
|
|
75
|
+
``` -->
|
|
76
|
+
### 1. Initialise an energy model
|
|
77
|
+
In this step, we define a classical energy function over binary spin configurations.
|
|
78
|
+
This energy model is the target distribution that the QeMCMC sampler will explore.
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
```python
|
|
83
|
+
import numpy as np
|
|
84
|
+
from qemcmc.model import EnergyModel
|
|
85
|
+
|
|
86
|
+
n = 4
|
|
87
|
+
h = np.array([-1.0, 0.5, 0.0, 2.0])
|
|
88
|
+
|
|
89
|
+
# Symmetric J
|
|
90
|
+
J = np.array([
|
|
91
|
+
[0.0, 1.2, 0.0, 0.0],
|
|
92
|
+
[1.2, 0.0, -0.7, 0.0],
|
|
93
|
+
[0.0, -0.7, 0.0, 0.4],
|
|
94
|
+
[0.0, 0.0, 0.4, 0.0],
|
|
95
|
+
])
|
|
96
|
+
|
|
97
|
+
couplings = [h, J]
|
|
98
|
+
|
|
99
|
+
model = EnergyModel(n=n, couplings=couplings, name="my_ising")
|
|
100
|
+
```
|
|
101
|
+
Here, h represents local fields and J encodes pairwise interactions in a standard Ising formulation. Higher-order coupling tensors can also be supplied.
|
|
102
|
+
|
|
103
|
+
### 2. (Optional) Define coarse graining
|
|
104
|
+
Coarse graining allows the sampler to propose local multi-spin updates on predefined subgroups, rather than updating all spins at once.
|
|
105
|
+
```python
|
|
106
|
+
from qemcmc.coarse_grain import CoarseGraining
|
|
107
|
+
|
|
108
|
+
cg = CoarseGraining(
|
|
109
|
+
n=n,
|
|
110
|
+
subgroups=[[0,1], [2,3,4], [1,3]],
|
|
111
|
+
subgroup_probs=[0.3, 0.5, 0.2],
|
|
112
|
+
)
|
|
113
|
+
```
|
|
114
|
+
Each subgroup specifies a set of spin indices that may be updated together.
|
|
115
|
+
At each MCMC step, a subgroup is sampled according to subgroup_probs.
|
|
116
|
+
|
|
117
|
+
### 3. Create and run QeMCMC
|
|
118
|
+
Finally, we initialise the quantum-enhanced Markov chain and generate a single proposal using simulated quantum time evolution.
|
|
119
|
+
```python
|
|
120
|
+
from qemcmc.qemcmc import QeMCMC
|
|
121
|
+
|
|
122
|
+
sampler = QeMCMC(
|
|
123
|
+
model=model,
|
|
124
|
+
gamma=(0.3, 0.6),
|
|
125
|
+
time=(1, 5),
|
|
126
|
+
temp=1.0,
|
|
127
|
+
delta_time=0.8,
|
|
128
|
+
coarse_graining=cg,
|
|
129
|
+
)
|
|
130
|
+
|
|
131
|
+
s = "01010"
|
|
132
|
+
s_prime = sampler.get_s_prime(s)
|
|
133
|
+
print("proposal:", s, "->", s_prime)
|
|
134
|
+
```
|
|
135
|
+
Here, each call to get_s_prime runs a quantum circuit to generate a proposal state conditioned on the current configuration.
|
|
136
|
+
|
|
137
|
+
## Coarse Graining
|
|
138
|
+
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]]`.
|
|
139
|
+
|
|
140
|
+
NOTE: All spins must belong to at least one subgroup and subgroups may overlap (i.e., a spin may belong to multiple subgroups).
|
|
141
|
+
|
|
142
|
+
The `CircuitMaker` will then automatically build the evolution circuit to perform coarse graining based on these subgroups.
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
## Documentation
|
|
146
|
+
|
|
147
|
+
QeMCMC's documentation is available at [docs](https://stuartferguson00.github.io/QeMCMC).
|
|
148
|
+
|
|
149
|
+
## License
|
|
150
|
+
|
|
151
|
+
Distributed under the MIT License. See `LICENSE` for more information.
|
|
152
|
+
|
|
153
|
+
## Authors
|
|
154
|
+
|
|
155
|
+
This project was created by Stuart Ferguson and maintained by Feroz Hassan.
|
|
156
|
+
|
|
157
|
+
For questions, suggestions, or collaboration, please feel free to contact the authors:
|
|
158
|
+
|
|
159
|
+
- S.A.Ferguson-3@sms.ed.ac.uk.
|
|
160
|
+
- fhassan2@ed.ac.uk
|
|
161
|
+
|
|
162
|
+
## Acknowledgements
|
|
163
|
+
|
|
164
|
+
- [pafloxy/quMCMC](https://github.com/pafloxy/quMCMC) for the foundational code.
|
|
165
|
+
- [Quantum-enhanced Markov Chain Monte Carlo](https://www.nature.com/articles/s41586-023-06095-4) by David Layden et al.
|
|
166
|
+
- [Quantum-enhanced MCMC for systems larger than your Quantum Computer](https://arxiv.org/abs/2405.04247) by S. Ferguson and P. Wallden.
|
|
167
|
+
|
|
168
|
+
---
|
|
169
|
+

|
qemcmc-0.1.0/README.md
ADDED
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
# Quantum-enhanced Markov Chain Monte Carlo Simulator
|
|
2
|
+
|
|
3
|
+
[](https://www.python.org/downloads/release/python-3130/)
|
|
4
|
+
[](https://quantum.cloud.ibm.com/docs/en/api/qiskit/release-notes/2.2)
|
|
5
|
+
[](https://docs.pennylane.ai/en/stable/)
|
|
6
|
+
[](https://opensource.org/licenses/MIT)
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
This is a lightweight research package for **Quantum-enhanced Markov Chain Monte Carlo** (QeMCMC) sampling over discrete spin/bitstring configurations.
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
The implementation is inspired by the numerics in [Layden's work on QeMCMC](https://www.nature.com/articles/s41586-023-06095-4) and builds upon the foundations of the [pafloxy/quMCMC](https://github.com/pafloxy/quMCMC) repository.
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
## Features
|
|
16
|
+
- **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
|
|
17
|
+
- **Automatic Hamiltonian Construction:** Build the corresponding **quantum Hamiltonian** based on the given couplings and run **Trotterised time evolution** with PennyLane's lightining qubit simulator
|
|
18
|
+
- **Coarse Graining**: Optionally use local updates on chosen subgroups of spins to scale proposals
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
## Installation
|
|
22
|
+
|
|
23
|
+
This project uses [`uv`](https://astral.sh/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](https://astral.sh/uv)
|
|
24
|
+
|
|
25
|
+
1. **Install `uv`:**
|
|
26
|
+
For macOS and Linux run:
|
|
27
|
+
```bash
|
|
28
|
+
curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
2. **Create a virtual environment:**
|
|
32
|
+
From the project's root directory, run:
|
|
33
|
+
```bash
|
|
34
|
+
uv sync
|
|
35
|
+
```
|
|
36
|
+
This will create a local `.venv` folder and install all required dependencies from `pyproject.toml` and `uv.lock`.
|
|
37
|
+
|
|
38
|
+
## Quick Start - Example 2D Ising Model
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
<!-- `model/energy_model.py`
|
|
42
|
+
|
|
43
|
+
```python
|
|
44
|
+
# Use our pre-defined base class to initialise an energy model
|
|
45
|
+
class EnergyModel():
|
|
46
|
+
...
|
|
47
|
+
|
|
48
|
+
# Or optionally define a problem specific energy model inheriting the base class EnergyModel
|
|
49
|
+
class your_energy_model(EnergyModel)
|
|
50
|
+
...
|
|
51
|
+
``` -->
|
|
52
|
+
### 1. Initialise an energy model
|
|
53
|
+
In this step, we define a classical energy function over binary spin configurations.
|
|
54
|
+
This energy model is the target distribution that the QeMCMC sampler will explore.
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
```python
|
|
59
|
+
import numpy as np
|
|
60
|
+
from qemcmc.model import EnergyModel
|
|
61
|
+
|
|
62
|
+
n = 4
|
|
63
|
+
h = np.array([-1.0, 0.5, 0.0, 2.0])
|
|
64
|
+
|
|
65
|
+
# Symmetric J
|
|
66
|
+
J = np.array([
|
|
67
|
+
[0.0, 1.2, 0.0, 0.0],
|
|
68
|
+
[1.2, 0.0, -0.7, 0.0],
|
|
69
|
+
[0.0, -0.7, 0.0, 0.4],
|
|
70
|
+
[0.0, 0.0, 0.4, 0.0],
|
|
71
|
+
])
|
|
72
|
+
|
|
73
|
+
couplings = [h, J]
|
|
74
|
+
|
|
75
|
+
model = EnergyModel(n=n, couplings=couplings, name="my_ising")
|
|
76
|
+
```
|
|
77
|
+
Here, h represents local fields and J encodes pairwise interactions in a standard Ising formulation. Higher-order coupling tensors can also be supplied.
|
|
78
|
+
|
|
79
|
+
### 2. (Optional) Define coarse graining
|
|
80
|
+
Coarse graining allows the sampler to propose local multi-spin updates on predefined subgroups, rather than updating all spins at once.
|
|
81
|
+
```python
|
|
82
|
+
from qemcmc.coarse_grain import CoarseGraining
|
|
83
|
+
|
|
84
|
+
cg = CoarseGraining(
|
|
85
|
+
n=n,
|
|
86
|
+
subgroups=[[0,1], [2,3,4], [1,3]],
|
|
87
|
+
subgroup_probs=[0.3, 0.5, 0.2],
|
|
88
|
+
)
|
|
89
|
+
```
|
|
90
|
+
Each subgroup specifies a set of spin indices that may be updated together.
|
|
91
|
+
At each MCMC step, a subgroup is sampled according to subgroup_probs.
|
|
92
|
+
|
|
93
|
+
### 3. Create and run QeMCMC
|
|
94
|
+
Finally, we initialise the quantum-enhanced Markov chain and generate a single proposal using simulated quantum time evolution.
|
|
95
|
+
```python
|
|
96
|
+
from qemcmc.qemcmc import QeMCMC
|
|
97
|
+
|
|
98
|
+
sampler = QeMCMC(
|
|
99
|
+
model=model,
|
|
100
|
+
gamma=(0.3, 0.6),
|
|
101
|
+
time=(1, 5),
|
|
102
|
+
temp=1.0,
|
|
103
|
+
delta_time=0.8,
|
|
104
|
+
coarse_graining=cg,
|
|
105
|
+
)
|
|
106
|
+
|
|
107
|
+
s = "01010"
|
|
108
|
+
s_prime = sampler.get_s_prime(s)
|
|
109
|
+
print("proposal:", s, "->", s_prime)
|
|
110
|
+
```
|
|
111
|
+
Here, each call to get_s_prime runs a quantum circuit to generate a proposal state conditioned on the current configuration.
|
|
112
|
+
|
|
113
|
+
## Coarse Graining
|
|
114
|
+
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]]`.
|
|
115
|
+
|
|
116
|
+
NOTE: All spins must belong to at least one subgroup and subgroups may overlap (i.e., a spin may belong to multiple subgroups).
|
|
117
|
+
|
|
118
|
+
The `CircuitMaker` will then automatically build the evolution circuit to perform coarse graining based on these subgroups.
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
## Documentation
|
|
122
|
+
|
|
123
|
+
QeMCMC's documentation is available at [docs](https://stuartferguson00.github.io/QeMCMC).
|
|
124
|
+
|
|
125
|
+
## License
|
|
126
|
+
|
|
127
|
+
Distributed under the MIT License. See `LICENSE` for more information.
|
|
128
|
+
|
|
129
|
+
## Authors
|
|
130
|
+
|
|
131
|
+
This project was created by Stuart Ferguson and maintained by Feroz Hassan.
|
|
132
|
+
|
|
133
|
+
For questions, suggestions, or collaboration, please feel free to contact the authors:
|
|
134
|
+
|
|
135
|
+
- S.A.Ferguson-3@sms.ed.ac.uk.
|
|
136
|
+
- fhassan2@ed.ac.uk
|
|
137
|
+
|
|
138
|
+
## Acknowledgements
|
|
139
|
+
|
|
140
|
+
- [pafloxy/quMCMC](https://github.com/pafloxy/quMCMC) for the foundational code.
|
|
141
|
+
- [Quantum-enhanced Markov Chain Monte Carlo](https://www.nature.com/articles/s41586-023-06095-4) by David Layden et al.
|
|
142
|
+
- [Quantum-enhanced MCMC for systems larger than your Quantum Computer](https://arxiv.org/abs/2405.04247) by S. Ferguson and P. Wallden.
|
|
143
|
+
|
|
144
|
+
---
|
|
145
|
+

|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Minimal makefile for Sphinx documentation
|
|
2
|
+
#
|
|
3
|
+
|
|
4
|
+
# You can set these variables from the command line, and also
|
|
5
|
+
# from the environment for the first two.
|
|
6
|
+
SPHINXOPTS ?=
|
|
7
|
+
SPHINXBUILD ?= sphinx-build
|
|
8
|
+
SOURCEDIR = source
|
|
9
|
+
BUILDDIR = build
|
|
10
|
+
|
|
11
|
+
# Put it first so that "make" without argument is like "make help".
|
|
12
|
+
help:
|
|
13
|
+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
|
14
|
+
|
|
15
|
+
.PHONY: help Makefile
|
|
16
|
+
|
|
17
|
+
# Catch-all target: route all unknown targets to Sphinx using the new
|
|
18
|
+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
|
19
|
+
%: Makefile
|
|
20
|
+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
@ECHO OFF
|
|
2
|
+
|
|
3
|
+
pushd %~dp0
|
|
4
|
+
|
|
5
|
+
REM Command file for Sphinx documentation
|
|
6
|
+
|
|
7
|
+
if "%SPHINXBUILD%" == "" (
|
|
8
|
+
set SPHINXBUILD=sphinx-build
|
|
9
|
+
)
|
|
10
|
+
set SOURCEDIR=source
|
|
11
|
+
set BUILDDIR=build
|
|
12
|
+
|
|
13
|
+
%SPHINXBUILD% >NUL 2>NUL
|
|
14
|
+
if errorlevel 9009 (
|
|
15
|
+
echo.
|
|
16
|
+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
|
|
17
|
+
echo.installed, then set the SPHINXBUILD environment variable to point
|
|
18
|
+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
|
|
19
|
+
echo.may add the Sphinx directory to PATH.
|
|
20
|
+
echo.
|
|
21
|
+
echo.If you don't have Sphinx installed, grab it from
|
|
22
|
+
echo.https://www.sphinx-doc.org/
|
|
23
|
+
exit /b 1
|
|
24
|
+
)
|
|
25
|
+
|
|
26
|
+
if "%1" == "" goto help
|
|
27
|
+
|
|
28
|
+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
|
|
29
|
+
goto end
|
|
30
|
+
|
|
31
|
+
:help
|
|
32
|
+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
|
|
33
|
+
|
|
34
|
+
:end
|
|
35
|
+
popd
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
|
|
2
|
+
|
|
3
|
+
autoapi==2.0.1
|
|
4
|
+
sphinx-autoapi==3.7.0
|
|
5
|
+
sphinx>=8
|
|
6
|
+
sphinx-copybutton==0.5.2
|
|
7
|
+
accessible-pygments==0.0.5
|
|
8
|
+
alabaster==1.0.0
|
|
9
|
+
babel==2.17.0
|
|
10
|
+
beautifulsoup4==4.14.2
|
|
11
|
+
certifi==2025.10.5
|
|
12
|
+
charset-normalizer==3.4.4
|
|
13
|
+
commonmark==0.9.1
|
|
14
|
+
docutils==0.21.2
|
|
15
|
+
furo==2025.9.25
|
|
16
|
+
idna==3.11
|
|
17
|
+
imagesize==1.4.1
|
|
18
|
+
Jinja2==3.1.6
|
|
19
|
+
linkify-it-py==2.0.3
|
|
20
|
+
markdown-it-py==4.0.0
|
|
21
|
+
MarkupSafe==3.0.3
|
|
22
|
+
mdit-py-plugins==0.5.0
|
|
23
|
+
mdurl==0.1.2
|
|
24
|
+
myst-parser==5.0.0
|
|
25
|
+
packaging==25.0
|
|
26
|
+
Pygments==2.19.2
|
|
27
|
+
PyYAML==6.0.3
|
|
28
|
+
recommonmark==0.7.1
|
|
29
|
+
requests==2.32.5
|
|
30
|
+
roman-numerals-py==3.1.0
|
|
31
|
+
snowballstemmer==3.0.1
|
|
32
|
+
soupsieve==2.8
|
|
33
|
+
Sphinx==8.2.3
|
|
34
|
+
sphinx-autodoc-typehints==3.5.2
|
|
35
|
+
sphinx-rtd-theme==3.0.2
|
|
36
|
+
sphinxcontrib-applehelp==2.0.0
|
|
37
|
+
sphinxcontrib-devhelp==2.0.0
|
|
38
|
+
sphinxcontrib-htmlhelp==2.1.0
|
|
39
|
+
sphinxcontrib-jquery==4.1
|
|
40
|
+
sphinxcontrib-jsmath==1.0.1
|
|
41
|
+
sphinxcontrib-qthelp==2.0.0
|
|
42
|
+
sphinxcontrib-serializinghtml==2.0.0
|
|
43
|
+
typing_extensions==4.15.0
|
|
44
|
+
uc-micro-py==1.0.3
|
|
45
|
+
urllib3==2.5.0
|
|
Binary file
|