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.
Files changed (51) hide show
  1. qemcmc-0.1.0/.github/workflows/docs.yaml +50 -0
  2. qemcmc-0.1.0/.github/workflows/publish.yaml +34 -0
  3. qemcmc-0.1.0/.gitignore +175 -0
  4. qemcmc-0.1.0/.python-version +1 -0
  5. qemcmc-0.1.0/LICENSE +21 -0
  6. qemcmc-0.1.0/PKG-INFO +169 -0
  7. qemcmc-0.1.0/README.md +145 -0
  8. qemcmc-0.1.0/docs/Makefile +20 -0
  9. qemcmc-0.1.0/docs/make.bat +35 -0
  10. qemcmc-0.1.0/docs/requirements.txt +45 -0
  11. qemcmc-0.1.0/docs/source/_static/logo-qsl.jpeg +0 -0
  12. qemcmc-0.1.0/docs/source/api.md +7 -0
  13. qemcmc-0.1.0/docs/source/authors.md +9 -0
  14. qemcmc-0.1.0/docs/source/coarse-graining.md +21 -0
  15. qemcmc-0.1.0/docs/source/conf.py +115 -0
  16. qemcmc-0.1.0/docs/source/energy-model.md +14 -0
  17. qemcmc-0.1.0/docs/source/example.md +63 -0
  18. qemcmc-0.1.0/docs/source/getting-started.md +16 -0
  19. qemcmc-0.1.0/docs/source/github.md +3 -0
  20. qemcmc-0.1.0/docs/source/index.md +38 -0
  21. qemcmc-0.1.0/docs/source/license.md +24 -0
  22. qemcmc-0.1.0/logo-qsl.jpeg +0 -0
  23. qemcmc-0.1.0/notebooks/H_E_graphs.py +168 -0
  24. qemcmc-0.1.0/notebooks/H_E_graphs_stu.py +209 -0
  25. qemcmc-0.1.0/notebooks/test.ipynb +263 -0
  26. qemcmc-0.1.0/notebooks/test.py +97 -0
  27. qemcmc-0.1.0/notebooks/tutorial.ipynb +462 -0
  28. qemcmc-0.1.0/pyproject.toml +36 -0
  29. qemcmc-0.1.0/setup.cfg +4 -0
  30. qemcmc-0.1.0/src/qemcmc/__init__.py +25 -0
  31. qemcmc-0.1.0/src/qemcmc/circuits.py +180 -0
  32. qemcmc-0.1.0/src/qemcmc/coarse_grain.py +28 -0
  33. qemcmc-0.1.0/src/qemcmc/main.py +78 -0
  34. qemcmc-0.1.0/src/qemcmc/model/__init__.py +4 -0
  35. qemcmc-0.1.0/src/qemcmc/model/energy_model.py +328 -0
  36. qemcmc-0.1.0/src/qemcmc/sampler/__init__.py +6 -0
  37. qemcmc-0.1.0/src/qemcmc/sampler/classical_mcmc.py +82 -0
  38. qemcmc-0.1.0/src/qemcmc/sampler/mcmc.py +162 -0
  39. qemcmc-0.1.0/src/qemcmc/sampler/qe_mcmc.py +150 -0
  40. qemcmc-0.1.0/src/qemcmc/spectralgap.py +162 -0
  41. qemcmc-0.1.0/src/qemcmc/utils/__init__.py +13 -0
  42. qemcmc-0.1.0/src/qemcmc/utils/helpers.py +308 -0
  43. qemcmc-0.1.0/src/qemcmc/utils/model_maker.py +62 -0
  44. qemcmc-0.1.0/src/qemcmc.egg-info/PKG-INFO +169 -0
  45. qemcmc-0.1.0/src/qemcmc.egg-info/SOURCES.txt +49 -0
  46. qemcmc-0.1.0/src/qemcmc.egg-info/dependency_links.txt +1 -0
  47. qemcmc-0.1.0/src/qemcmc.egg-info/entry_points.txt +2 -0
  48. qemcmc-0.1.0/src/qemcmc.egg-info/requires.txt +13 -0
  49. qemcmc-0.1.0/src/qemcmc.egg-info/top_level.txt +1 -0
  50. qemcmc-0.1.0/uv.lock +1388 -0
  51. 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
@@ -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
+ [![Python 3.13+](https://img.shields.io/badge/Python-3.13+-blue.svg)](https://www.python.org/downloads/release/python-3130/)
28
+ [![Qiskit 2.2](https://img.shields.io/badge/Qiskit-2.2-cyan)](https://quantum.cloud.ibm.com/docs/en/api/qiskit/release-notes/2.2)
29
+ [![PennyLane 0.44](https://img.shields.io/badge/PennyLane-0.44-pink)](https://docs.pennylane.ai/en/stable/)
30
+ [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](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
+ ![alt text](logo-qsl.jpeg)
qemcmc-0.1.0/README.md ADDED
@@ -0,0 +1,145 @@
1
+ # Quantum-enhanced Markov Chain Monte Carlo Simulator
2
+
3
+ [![Python 3.13+](https://img.shields.io/badge/Python-3.13+-blue.svg)](https://www.python.org/downloads/release/python-3130/)
4
+ [![Qiskit 2.2](https://img.shields.io/badge/Qiskit-2.2-cyan)](https://quantum.cloud.ibm.com/docs/en/api/qiskit/release-notes/2.2)
5
+ [![PennyLane 0.44](https://img.shields.io/badge/PennyLane-0.44-pink)](https://docs.pennylane.ai/en/stable/)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](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
+ ![alt text](logo-qsl.jpeg)
@@ -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