QCut 2.1.4__tar.gz → 2.3.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 (154) hide show
  1. {qcut-2.1.4 → qcut-2.3.0}/CHANGELOG.rst +85 -0
  2. {qcut-2.1.4 → qcut-2.3.0}/PKG-INFO +76 -43
  3. {qcut-2.1.4 → qcut-2.3.0}/QCut/__init__.py +2 -0
  4. {qcut-2.1.4 → qcut-2.3.0}/QCut/cutcircuit.py +71 -3
  5. qcut-2.3.0/QCut/cutting/__init__.py +1 -0
  6. qcut-2.3.0/QCut/errors/__init__.py +1 -0
  7. qcut-2.3.0/QCut/execution/__init__.py +1 -0
  8. {qcut-2.1.4 → qcut-2.3.0}/QCut/execution/backend_utility.py +63 -37
  9. {qcut-2.1.4 → qcut-2.3.0}/QCut/execution/circuit_knitting.py +176 -74
  10. qcut-2.3.0/QCut/execution/distribution.py +447 -0
  11. qcut-2.3.0/QCut/execution/observables.py +299 -0
  12. {qcut-2.1.4 → qcut-2.3.0}/QCut/execution/postprocess.py +55 -12
  13. qcut-2.3.0/QCut/execution/probabilities.py +590 -0
  14. {qcut-2.1.4 → qcut-2.3.0}/QCut/options.py +19 -3
  15. qcut-2.3.0/QCut/qpd/__init__.py +1 -0
  16. qcut-2.3.0/QCut/utils/__init__.py +1 -0
  17. {qcut-2.1.4 → qcut-2.3.0}/QCut/utils/circuit_utils.py +130 -1
  18. {qcut-2.1.4 → qcut-2.3.0}/QCut.egg-info/PKG-INFO +76 -43
  19. {qcut-2.1.4 → qcut-2.3.0}/QCut.egg-info/SOURCES.txt +22 -2
  20. {qcut-2.1.4 → qcut-2.3.0}/QCut.egg-info/requires.txt +0 -1
  21. {qcut-2.1.4 → qcut-2.3.0}/QCut.egg-info/scm_file_list.json +22 -2
  22. qcut-2.3.0/QCut.egg-info/scm_version.json +8 -0
  23. qcut-2.3.0/QCut.egg-info/top_level.txt +1 -0
  24. {qcut-2.1.4 → qcut-2.3.0}/README.md +70 -36
  25. {qcut-2.1.4 → qcut-2.3.0}/docs/Options.rst +31 -2
  26. qcut-2.3.0/docs/QCut.rst +10 -0
  27. {qcut-2.1.4 → qcut-2.3.0}/docs/Usage.rst +43 -19
  28. qcut-2.3.0/docs/_static/images/diagram/qcut-diagram-left-logo.png +0 -0
  29. qcut-2.3.0/docs/_static/images/logos/qcut-banner-transparent.png +0 -0
  30. qcut-2.3.0/docs/_static/images/logos/qcut-banner-transparent.svg +110 -0
  31. qcut-2.3.0/docs/_static/images/logos/qcut-banner.png +0 -0
  32. qcut-2.3.0/docs/_static/images/logos/qcut-banner.svg +110 -0
  33. qcut-2.3.0/docs/_static/images/logos/qcut-banner@2x.png +0 -0
  34. qcut-2.3.0/docs/_static/images/logos/qcut-logo-1024.png +0 -0
  35. qcut-2.3.0/docs/_static/images/logos/qcut-logo-2048.png +0 -0
  36. qcut-2.3.0/docs/_static/images/logos/qcut-logo-transparent-2048.png +0 -0
  37. qcut-2.3.0/docs/_static/images/logos/qcut-logo-transparent.svg +102 -0
  38. qcut-2.3.0/docs/_static/images/logos/qcut-logo.svg +102 -0
  39. qcut-2.3.0/docs/_templates/page-toc.html +27 -0
  40. {qcut-2.1.4 → qcut-2.3.0}/docs/conf.py +2 -2
  41. {qcut-2.1.4 → qcut-2.3.0}/docs/examples/AutomaticCuts.rst +3 -3
  42. {qcut-2.1.4 → qcut-2.3.0}/docs/examples/GateCuts.rst +1 -2
  43. {qcut-2.1.4 → qcut-2.3.0}/docs/examples/ParallelBackends.rst +1 -2
  44. {qcut-2.1.4 → qcut-2.3.0}/docs/examples/WireCuts.rst +1 -2
  45. {qcut-2.1.4 → qcut-2.3.0}/docs/index.rst +13 -6
  46. {qcut-2.1.4 → qcut-2.3.0}/docs/notebooks/QCutBasicUsage.ipynb +8 -8
  47. {qcut-2.1.4 → qcut-2.3.0}/docs/notebooks/QCutOptionsExample.ipynb +7 -8
  48. qcut-2.3.0/docs/notebooks/QCutProbabilities.ipynb +359 -0
  49. qcut-2.3.0/docs/notebooks/QCutQAOAExample.ipynb +507 -0
  50. {qcut-2.1.4 → qcut-2.3.0}/docs/theory/LOCC_wire_derivation.md +0 -2
  51. qcut-2.3.0/docs/theory/Probability_reconstruction.md +68 -0
  52. {qcut-2.1.4 → qcut-2.3.0}/pyproject.toml +9 -7
  53. {qcut-2.1.4 → qcut-2.3.0}/tests/solutions_1q.py +6 -6
  54. {qcut-2.1.4 → qcut-2.3.0}/tests/solutions_automatic_cuts.py +6 -7
  55. {qcut-2.1.4 → qcut-2.3.0}/tests/test_1q_QCut.py +1 -2
  56. {qcut-2.1.4 → qcut-2.3.0}/tests/test_consolidate.py +10 -10
  57. {qcut-2.1.4 → qcut-2.3.0}/tests/test_cut_circuit.py +7 -7
  58. qcut-2.3.0/tests/test_deduplication.py +406 -0
  59. qcut-2.3.0/tests/test_distribution.py +331 -0
  60. {qcut-2.1.4 → qcut-2.3.0}/tests/test_gate_cut.py +1 -2
  61. {qcut-2.1.4 → qcut-2.3.0}/tests/test_generic_gate_cuts.py +7 -6
  62. {qcut-2.1.4 → qcut-2.3.0}/tests/test_iqm_backend.py +14 -14
  63. {qcut-2.1.4 → qcut-2.3.0}/tests/test_joint_cuts.py +20 -8
  64. {qcut-2.1.4 → qcut-2.3.0}/tests/test_locc_wire_cuts.py +3 -3
  65. {qcut-2.1.4 → qcut-2.3.0}/tests/test_new_gate_cuts.py +4 -5
  66. qcut-2.3.0/tests/test_observables.py +319 -0
  67. {qcut-2.1.4 → qcut-2.3.0}/tests/test_parallel.py +19 -9
  68. qcut-2.3.0/tests/test_probabilities.py +584 -0
  69. {qcut-2.1.4 → qcut-2.3.0}/tests/test_qcut_backend_utils.py +54 -6
  70. {qcut-2.1.4 → qcut-2.3.0}/tests/test_sampling.py +4 -6
  71. {qcut-2.1.4 → qcut-2.3.0}/uv.lock +206 -186
  72. qcut-2.1.4/QCut/execution/probabilities.py +0 -185
  73. qcut-2.1.4/QCut.egg-info/scm_version.json +0 -8
  74. qcut-2.1.4/QCut.egg-info/top_level.txt +0 -4
  75. qcut-2.1.4/docs/QCut.rst +0 -8
  76. qcut-2.1.4/docs/_autosummary/QCut.rst +0 -6
  77. qcut-2.1.4/docs/_static/images/QCut-logo.jpg +0 -0
  78. qcut-2.1.4/docs/notebooks/QCutProbabilities.ipynb +0 -322
  79. qcut-2.1.4/docs/notebooks/QCutQAOAExample.ipynb +0 -494
  80. qcut-2.1.4/docs/theory/Probability_reconstruction.md +0 -67
  81. qcut-2.1.4/tests/test_probabilities.py +0 -230
  82. {qcut-2.1.4 → qcut-2.3.0}/.github/ISSUE_TEMPLATE/bug_report.md +0 -0
  83. {qcut-2.1.4 → qcut-2.3.0}/.github/ISSUE_TEMPLATE/config.yml +0 -0
  84. {qcut-2.1.4 → qcut-2.3.0}/.github/ISSUE_TEMPLATE/feature_request.md +0 -0
  85. {qcut-2.1.4 → qcut-2.3.0}/.github/PULL_REQUEST_TEMPLATE.md +0 -0
  86. {qcut-2.1.4 → qcut-2.3.0}/.github/dependabot.yml +0 -0
  87. {qcut-2.1.4 → qcut-2.3.0}/.github/workflows/ci.yml +0 -0
  88. {qcut-2.1.4 → qcut-2.3.0}/.github/workflows/publish_docs.yml +0 -0
  89. {qcut-2.1.4 → qcut-2.3.0}/.github/workflows/publish_to_pypi.yml +0 -0
  90. {qcut-2.1.4 → qcut-2.3.0}/.github/workflows/tag_and_release.yml +0 -0
  91. {qcut-2.1.4 → qcut-2.3.0}/.gitignore +0 -0
  92. {qcut-2.1.4 → qcut-2.3.0}/CONTRIBUTING.md +0 -0
  93. {qcut-2.1.4 → qcut-2.3.0}/LICENSE +0 -0
  94. {qcut-2.1.4 → qcut-2.3.0}/QCut/QCutFind/__init__.py +0 -0
  95. {qcut-2.1.4 → qcut-2.3.0}/QCut/QCutFind/combine_subcircuits.py +0 -0
  96. {qcut-2.1.4 → qcut-2.3.0}/QCut/QCutFind/cut_finding.py +0 -0
  97. {qcut-2.1.4 → qcut-2.3.0}/QCut/QCutFind/graph_circuit_utils.py +0 -0
  98. {qcut-2.1.4 → qcut-2.3.0}/QCut/QCutFind/metis.py +0 -0
  99. {qcut-2.1.4 → qcut-2.3.0}/QCut/QCutFind/refine.py +0 -0
  100. {qcut-2.1.4 → qcut-2.3.0}/QCut/cutlocation.py +0 -0
  101. {qcut-2.1.4 → qcut-2.3.0}/QCut/cutting/circuit_preparation.py +0 -0
  102. {qcut-2.1.4 → qcut-2.3.0}/QCut/cutting/consolidate.py +0 -0
  103. {qcut-2.1.4 → qcut-2.3.0}/QCut/errors/qcuterror.py +0 -0
  104. {qcut-2.1.4 → qcut-2.3.0}/QCut/execution/basis_transform.py +0 -0
  105. {qcut-2.1.4 → qcut-2.3.0}/QCut/execution/move_routing.py +0 -0
  106. {qcut-2.1.4 → qcut-2.3.0}/QCut/execution/parallel.py +0 -0
  107. {qcut-2.1.4 → qcut-2.3.0}/QCut/execution/qcutresult.py +0 -0
  108. {qcut-2.1.4 → qcut-2.3.0}/QCut/qpd/bundle.py +0 -0
  109. {qcut-2.1.4 → qcut-2.3.0}/QCut/qpd/qpd.py +0 -0
  110. {qcut-2.1.4 → qcut-2.3.0}/QCut/qpd/qpd_analytic.py +0 -0
  111. {qcut-2.1.4 → qcut-2.3.0}/QCut/qpd/qpd_gates.py +0 -0
  112. {qcut-2.1.4 → qcut-2.3.0}/QCut/qpd/qpd_generate.py +0 -0
  113. {qcut-2.1.4 → qcut-2.3.0}/QCut/qpd/qpd_joint.py +0 -0
  114. {qcut-2.1.4 → qcut-2.3.0}/QCut/qpd/qpd_locc.py +0 -0
  115. {qcut-2.1.4 → qcut-2.3.0}/QCut/qpd/qpd_operations.py +0 -0
  116. {qcut-2.1.4 → qcut-2.3.0}/QCut.egg-info/dependency_links.txt +0 -0
  117. {qcut-2.1.4 → qcut-2.3.0}/benchmarks/QCutVsAddon.ipynb +0 -0
  118. {qcut-2.1.4 → qcut-2.3.0}/docs/Acknowledgement.rst +0 -0
  119. {qcut-2.1.4 → qcut-2.3.0}/docs/Changelog.rst +0 -0
  120. {qcut-2.1.4 → qcut-2.3.0}/docs/Examples.rst +0 -0
  121. {qcut-2.1.4 → qcut-2.3.0}/docs/License.rst +0 -0
  122. {qcut-2.1.4 → qcut-2.3.0}/docs/Makefile +0 -0
  123. {qcut-2.1.4 → qcut-2.3.0}/docs/Notebooks.rst +0 -0
  124. {qcut-2.1.4 → qcut-2.3.0}/docs/Theory.rst +0 -0
  125. {qcut-2.1.4 → qcut-2.3.0}/docs/_static/images/circ1.png +0 -0
  126. {qcut-2.1.4 → qcut-2.3.0}/docs/_static/images/circ10.png +0 -0
  127. {qcut-2.1.4 → qcut-2.3.0}/docs/_static/images/circ11.png +0 -0
  128. {qcut-2.1.4 → qcut-2.3.0}/docs/_static/images/circ1_old.png +0 -0
  129. {qcut-2.1.4 → qcut-2.3.0}/docs/_static/images/circ2.png +0 -0
  130. {qcut-2.1.4 → qcut-2.3.0}/docs/_static/images/circ2_old.png +0 -0
  131. {qcut-2.1.4 → qcut-2.3.0}/docs/_static/images/circ3.png +0 -0
  132. {qcut-2.1.4 → qcut-2.3.0}/docs/_static/images/circ3_old.png +0 -0
  133. {qcut-2.1.4 → qcut-2.3.0}/docs/_static/images/circ4.png +0 -0
  134. {qcut-2.1.4 → qcut-2.3.0}/docs/_static/images/circ4_odl.png +0 -0
  135. {qcut-2.1.4 → qcut-2.3.0}/docs/_static/images/circ5.png +0 -0
  136. {qcut-2.1.4 → qcut-2.3.0}/docs/_static/images/circ6.png +0 -0
  137. {qcut-2.1.4 → qcut-2.3.0}/docs/_static/images/circ7.png +0 -0
  138. {qcut-2.1.4 → qcut-2.3.0}/docs/_static/images/circ8.png +0 -0
  139. {qcut-2.1.4 → qcut-2.3.0}/docs/_static/images/circ9.png +0 -0
  140. {qcut-2.1.4 → qcut-2.3.0}/docs/_static/images/probs1.png +0 -0
  141. {qcut-2.1.4 → qcut-2.3.0}/docs/make.bat +0 -0
  142. {qcut-2.1.4 → qcut-2.3.0}/docs/theory/CZ_derivation.md +0 -0
  143. {qcut-2.1.4 → qcut-2.3.0}/docs/theory/General_2q_derivation.md +0 -0
  144. {qcut-2.1.4 → qcut-2.3.0}/docs/theory/Joint_rotation_derivation.md +0 -0
  145. {qcut-2.1.4 → qcut-2.3.0}/docs/theory/SWAP_derivation.md +0 -0
  146. {qcut-2.1.4 → qcut-2.3.0}/docs/theory/Wire_derivation.md +0 -0
  147. {qcut-2.1.4 → qcut-2.3.0}/setup.cfg +0 -0
  148. {qcut-2.1.4 → qcut-2.3.0}/tag-from-pipeline.sh +0 -0
  149. {qcut-2.1.4 → qcut-2.3.0}/tests/__init__.py +0 -0
  150. {qcut-2.1.4 → qcut-2.3.0}/tests/test_automatic_cuts.py +0 -0
  151. {qcut-2.1.4 → qcut-2.3.0}/tests/test_qcuterror.py +0 -0
  152. {qcut-2.1.4 → qcut-2.3.0}/tests/test_qpd_analytic.py +0 -0
  153. {qcut-2.1.4 → qcut-2.3.0}/tests/test_qpd_generate.py +0 -0
  154. {qcut-2.1.4 → qcut-2.3.0}/tox.ini +0 -0
@@ -2,6 +2,91 @@
2
2
  Changelog
3
3
  =========
4
4
 
5
+ **Version 2.3.0**
6
+ =================
7
+
8
+ Remove Qiskit-Aer dependency
9
+ ----------------------------
10
+
11
+ - :code:`run()` and :code:`run_cut_circuit()` no longer default to :code:`AerSimulator()`;
12
+ pass a backend or sampler. :code:`qiskit-aer` is no longer installed with QCut, so
13
+ install it separately to simulate.
14
+ - :code:`transpile_subcircuits()` and :code:`transpile_experiments()` read a backend's
15
+ public :code:`target` rather than :code:`_target`, which Aer never fills in. Transpiling
16
+ for :code:`AerSimulator` works, and :code:`run_cut_circuit()` transpiles only for a
17
+ backend with a coupling map.
18
+
19
+ Deduplicated experiment circuits
20
+ --------------------------------
21
+
22
+ - A run now submits each *distinct* experiment circuit once and shares its result with
23
+ every slot it fills.
24
+ - :code:`shots` still means shots per circuit, so a run spends that many on each
25
+ distinct circuit and the total drops by the same factor. What the old total bought
26
+ was re-measuring circuits already measured. Sharing a sample between groups leaves the estimate unbiased,
27
+ since the groups are summed rather than multiplied.
28
+ - :code:`estimate_run()` counts the circuits and shots that are actually submitted, so
29
+ it still matches the run exactly.
30
+ - :code:`CutOptions(deduplicate=False)` restores one submission per slot.
31
+ :code:`CutExperiment.num_circuits` is unchanged: it still counts the circuits the
32
+ decomposition calls for.
33
+ - Experiments whose wire cuts communicate are unaffected for now. Their first wave
34
+ already shares circuits between the groups that differ only in the label they answer.
35
+
36
+ **Version 2.2.0**
37
+ =================
38
+
39
+ Breaking changes
40
+ ----------------
41
+
42
+ - A :code:`SparsePauliOp` is now **one** observable, the weighted sum of its terms, as
43
+ it is for :code:`EstimatorV2`. It used to be read as a list of observables, one
44
+ expectation value per Pauli, with its coefficients ignored. To keep that reading,
45
+ pass the labels themselves: :code:`SparsePauliOp(["IZ", "ZI"])` becomes
46
+ :code:`["IZ", "ZI"]`.
47
+ - The expectation values are shaped like the observables given, as an estimator's are,
48
+ so one observable comes back as a zero-dimensional array and a list of :code:`n` as
49
+ :code:`(n,)`.
50
+ - :code:`CutExperiment.observables` is now the :code:`ObservablesArray` that was asked
51
+ for, and has no :code:`len()`, use :code:`.size` or :code:`.shape`. The Pauli terms
52
+ the circuits actually measure are :code:`CutExperiment.observable_terms`.
53
+ - :code:`quasi_probabilities()`, :code:`nearest_probabilities()` and :code:`counts()`
54
+ return, by default, the ten most likely bitstrings rather than all of them, most likely first.
55
+ All three take :code:`top` for a different number and :code:`top=None` for the
56
+ previous behaviour. Note that :code:`counts()` sums to :code:`shots` only with :code:`top=None` and
57
+ Only :code:`quasi_probabilities()` gets cheaper this way since the other two project onto the
58
+ nearest physical distribution first.
59
+
60
+ Reconstructing a distribution no longer costs :code:`2**k`
61
+ ----------------------------------------------------------
62
+
63
+ - Reconstructing a distribution over :code:`k` qubits is now flat in :code:`k` rather
64
+ than exponential in it with a proper reconstruction method. See `the
65
+ derivation <https://jooniv.github.io/QCut/theory/Probability_reconstruction.html>`__.
66
+ - The distribution is held in that product form, so three new queries never expand it:
67
+ :code:`top(count)` gives the most likely bitstrings, exactly, by branch and bound
68
+ (measured at 17 ms and 0.2 MB for the top 100 of 2\ :sup:`24`, against 270 ms and
69
+ 384 MB just to hold the values); :code:`probability_of(bitstring)` gives one value in
70
+ about 25 microseconds whatever :code:`k` is; and :code:`marginal(qubits)` gives a
71
+ coarser distribution over a subset. :code:`probabilities()` returns every value as a
72
+ numpy array.
73
+ - The observables of an experiment given :code:`qubits` are built on demand, so nothing
74
+ pays for the :code:`2**k` Pauli labels unless it asks for them, and the weights
75
+ between them and the terms are never written out at all. Estimating them with
76
+ :code:`estimate_expectation_values()` still works.
77
+ - Reconstruction is now sparse, costing shots rather than :code:`2**num_qubits` per subcircuit.
78
+ - Fixed :code:`top()` skipping unmeasured outcomes
79
+
80
+ Observables as qiskit's estimator takes them
81
+ --------------------------------------------
82
+
83
+ - :code:`observables` now takes anything qiskit's estimator takes: a Pauli label, a
84
+ :code:`Pauli`, a :code:`SparsePauliOp`, a :code:`SparseObservable` (qiskit 2.1+), a
85
+ :code:`{label: coefficient}` mapping, or any nested sequence of those. Coefficients
86
+ are applied rather than ignored.
87
+ - Projector terms are supported: :code:`0 1 + - r l`, whether written as labels or
88
+ carried by a :code:`SparseObservable` (qiskit 2.1+).
89
+
5
90
  **Version 2.1.4**
6
91
  =================
7
92
  - Small fixes to transpilation on IQM Star backends
@@ -1,8 +1,8 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: QCut
3
- Version: 2.1.4
3
+ Version: 2.3.0
4
4
  Summary: QCut is a quantum circuit knitting package built on top of qiskit for performing gate cuts and resetless wire cuts allowing simulation of larger quantum circuits on smaller quantum devices or simulators at the cost of a circuit overhead.
5
- Author-email: Joonas Nivala <joonas.nivala@gmail.com>
5
+ Author-email: Joonas Nivala <joonas.nivala@csc.fi>, FiQCI <servicedesk@csc.fi>
6
6
  License: Apache License
7
7
  Version 2.0, January 2004
8
8
  http://www.apache.org/licenses/
@@ -205,10 +205,10 @@ License: Apache License
205
205
  See the License for the specific language governing permissions and
206
206
  limitations under the License.
207
207
 
208
- Project-URL: homepage, https://github.com/JooNiv/QCut
209
- Project-URL: documentation, https://jooniv.github.io/QCut/
210
- Project-URL: repository, https://github.com/JooNiv/QCut.git
211
- Project-URL: changelog, https://github.com/JooNiv/QCut/blob/main/CHANGELOG.rst
208
+ Project-URL: homepage, https://github.com/FiQCI/QCut
209
+ Project-URL: documentation, https://fiqci.fi/QCut/
210
+ Project-URL: repository, https://github.com/FiQCI/QCut.git
211
+ Project-URL: changelog, https://github.com/FiQCI/QCut/blob/main/CHANGELOG.rst
212
212
  Classifier: Programming Language :: Python :: 3 :: Only
213
213
  Classifier: Programming Language :: Python :: 3.11
214
214
  Classifier: Programming Language :: Python :: 3.12
@@ -219,7 +219,6 @@ Description-Content-Type: text/markdown
219
219
  License-File: LICENSE
220
220
  Requires-Dist: qiskit<3.0,>=1.1
221
221
  Requires-Dist: numpy
222
- Requires-Dist: qiskit-aer<0.18
223
222
  Requires-Dist: pymetis==2025.2.2
224
223
  Provides-Extra: dev
225
224
  Requires-Dist: pytest; extra == "dev"
@@ -258,6 +257,8 @@ Dynamic: license-file
258
257
 
259
258
  # QCut
260
259
 
260
+ <img src="docs/_static/images/diagram/qcut-diagram-left-logo.png" alt="QCut Diagram" width="1000">
261
+
261
262
  QCut is a quantum circuit knitting package built on top of qiskit for performing gate cuts and resetless wire cuts allowing simulation of larger quantum circuits on smaller quantum devices or simulators at the cost of a circuit overhead. QCut has been designed and tested to work with IQM's qpus, and the Finnish Quantum Computing Infrastructure ([FiQCI](https://fiqci.fi/)).
262
263
 
263
264
  QCut has been built at CSC - IT Center for Science (Finnish IT Center for Science).
@@ -266,10 +267,10 @@ Check out [docs](https://jooniv.github.io/QCut/) for instructions and more examp
266
267
 
267
268
  # Installation
268
269
 
269
- For installation a UNIX-like system is currently needed due to pymetis being used for automatic cut finding. On Windows use WSL
270
+ For installation a UNIX-like system is currently needed due to [PyMetis](https://github.com/inducer/pymetis) being used for automatic cut finding. On Windows use WSL
270
271
 
271
272
  **Pip:**
272
- Installation should be done via `uv`
273
+ Installation should be done via [`uv`](https://docs.astral.sh/uv/)
273
274
 
274
275
  ```bash
275
276
  uv pip install QCut
@@ -279,6 +280,8 @@ uv add QCut
279
280
 
280
281
  If using other than the default Qiskit version (newest) it is recommended to install Qiskit first before installing QCut.
281
282
 
283
+ QCut does not install a simulator. The examples below run on [Qiskit Aer](https://github.com/Qiskit/qiskit-aer), which needs `uv pip install qiskit-aer`.
284
+
282
285
  **IQM hardware and fake backends:**
283
286
 
284
287
  ```bash
@@ -287,7 +290,7 @@ uv pip install "QCut[iqm]"
287
290
  uv add "QCut[iqm]"
288
291
  ```
289
292
 
290
- This pulls in IQM's Qiskit adapter, which supports Qiskit 1.0 up to but not including
293
+ This pulls in IQM's Qiskit adapter ([iqm-client](https://docs.iqm.tech/iqm-client/)), which supports Qiskit 1.0 up to but not including
291
294
  2.2, so installing it will hold Qiskit below 2.2. Install it into an environment whose
292
295
  Qiskit is already in that range if you would rather the resolver did not move it.
293
296
 
@@ -295,6 +298,7 @@ After installing you can simply import what you need:
295
298
 
296
299
  ```python
297
300
  from iqm.qiskit_iqm import IQMFakeAdonis
301
+
298
302
  backend = IQMFakeAdonis()
299
303
  ```
300
304
 
@@ -340,7 +344,10 @@ from qiskit import QuantumCircuit, transpile
340
344
  from qiskit.circuit.library import CXGate
341
345
  from qiskit.quantum_info import SparsePauliOp
342
346
  from qiskit_aer import AerSimulator
343
- from qiskit.primitives import StatevectorEstimator as Estimator, BackendEstimatorV2 as BackendEstimator
347
+ from qiskit.primitives import (
348
+ StatevectorEstimator as Estimator,
349
+ BackendEstimatorV2 as BackendEstimator,
350
+ )
344
351
  from iqm.qiskit_iqm import IQMFakeAdonis
345
352
  ```
346
353
 
@@ -350,11 +357,11 @@ from iqm.qiskit_iqm import IQMFakeAdonis
350
357
  circuit = QuantumCircuit(5)
351
358
 
352
359
  for qubit in range(5):
353
- circuit.ry(0.4 + 0.3*qubit, qubit)
354
- circuit.cx(0,1)
355
- circuit.cx(1,2)
356
- circuit.cx(2,3)
357
- circuit.cx(3,4)
360
+ circuit.ry(0.4 + 0.3 * qubit, qubit)
361
+ circuit.cx(0, 1)
362
+ circuit.cx(1, 2)
363
+ circuit.cx(2, 3)
364
+ circuit.cx(3, 4)
358
365
 
359
366
  circuit.draw("mpl")
360
367
  ```
@@ -369,12 +376,12 @@ Note that here we don't insert any measurements. Measurements will be automatica
369
376
  marked_circuit = QuantumCircuit(5)
370
377
 
371
378
  for qubit in range(5):
372
- marked_circuit.ry(0.4 + 0.3*qubit, qubit)
373
- marked_circuit.cx(0,1)
379
+ marked_circuit.ry(0.4 + 0.3 * qubit, qubit)
380
+ marked_circuit.cx(0, 1)
374
381
  marked_circuit.append(**cutGate(CXGate(), 1, 2))
375
- marked_circuit.cx(2,3)
382
+ marked_circuit.cx(2, 3)
376
383
  marked_circuit.append(cut(), [3])
377
- marked_circuit.cx(3,4)
384
+ marked_circuit.cx(3, 4)
378
385
 
379
386
  marked_circuit.decompose(gates_to_decompose=["CutGate"]).draw("mpl")
380
387
  ```
@@ -416,8 +423,13 @@ cut_circuit.subcircuits[2].draw("mpl")
416
423
 
417
424
  **5: Generate experiment circuits**
418
425
 
426
+ Observables are given the way Qiskit's estimator takes them: a Pauli label, a `Pauli`, a
427
+ `SparsePauliOp`, a `SparseObservable` (qiskit 2.1+), a `{label: coefficient}` mapping,
428
+ or any nested
429
+ sequence of those. The expectation values come back shaped like what you pass.
430
+
419
431
  ```python
420
- observables = SparsePauliOp(["IIIIZ", "IIIZI", "IIZII", "IIIZZ"])
432
+ observables = ["IIIIZ", "IIIZI", "IIZII", "IIIZZ"]
421
433
 
422
434
  cut_experiment = ck.get_experiment_circuits(cut_circuit, observables)
423
435
 
@@ -520,8 +532,8 @@ finder's own options and how it chooses.
520
532
  Two helpers, `transpile_subcircuits()` and `transpile_experiments()` , differing in when they run:
521
533
 
522
534
  ```python
523
- fake = IQMFakeAdonis() #noisy
524
- sim = AerSimulator() #ideal
535
+ fake = IQMFakeAdonis() # noisy
536
+ sim = AerSimulator() # ideal
525
537
  ```
526
538
 
527
539
  `transpile_circuits()` does whichever of the two the thing it is given calls for. Each
@@ -563,12 +575,18 @@ The cost of an experiment run can be checked before submission:
563
575
  print(ck.estimate_run(cut_experiment, shots=4096, max_batch_size=40))
564
576
  ```
565
577
 
566
- `Experiment will run 144 circuits in 4 jobs with a total of 589824 shots. See the returned object for the breakdown.`
578
+ `Experiment will run 31 circuits in 1 jobs with a total of 126976 shots. See the returned object for the breakdown.`
567
579
 
568
580
  ```python
569
- {'job1': JobEstimate(circuits=40, shots=4096), 'job2': JobEstimate(circuits=40, shots=4096), ...}
581
+ {"job1": JobEstimate(circuits=31, shots=4096)}
570
582
  ```
571
583
 
584
+ 31 circuits, not the 144 the decomposition calls for: a subcircuit's experiment circuit
585
+ depends only on the QPD terms of the cuts touching it and on the measurement setting
586
+ over its own qubits, so most of them repeat. Each distinct one is submitted once and its
587
+ result shared, which is where the saving comes from. `shots` still means shots per
588
+ circuit. Pass `CutOptions(deduplicate=False)` to submit one circuit per slot instead.
589
+
572
590
  Exact for non-cummunicating runs. Runs whose wire cuts communicate get executed in waves so that
573
591
  each wave after the first spends its shots on what the one before it measured. For these jobs
574
592
  the circuit count is exact and job and shot counts are estimates.
@@ -596,24 +614,26 @@ and `BackendSamplerV2` are both fine.
596
614
  Comparing against the exact and noisy expectation values of the original circuit:
597
615
 
598
616
  ```python
599
- obs = [ob.to_label() for ob in observables.paulis]
600
-
601
617
  estimator = Estimator()
602
- exact_expvals = [e.data.evs for e in
603
- estimator.run([(x) for x in zip([circuit] * len(obs), obs)]).result()
618
+ exact_expvals = [
619
+ e.data.evs
620
+ for e in estimator.run(
621
+ [(x) for x in zip([circuit] * len(observables), observables)]
622
+ ).result()
604
623
  ]
605
624
 
606
625
  tr = transpile(circuit, backend=fake)
607
626
 
608
- tr_obs = observables.apply_layout(tr.layout)
609
-
610
627
  tr_obs_separate = [
611
- SparsePauliOp(pauli.to_label()) for pauli in tr_obs.paulis
628
+ SparsePauliOp(label).apply_layout(tr.layout) for label in observables
612
629
  ]
613
630
 
614
631
  fake_estimator = BackendEstimator(backend=fake)
615
- exps = [e.data.evs for e in
616
- fake_estimator.run([(x) for x in zip([tr] * len(tr_obs_separate), tr_obs_separate)]).result()
632
+ exps = [
633
+ e.data.evs
634
+ for e in fake_estimator.run(
635
+ [(x) for x in zip([tr] * len(tr_obs_separate), tr_obs_separate)]
636
+ ).result()
617
637
  ]
618
638
  ```
619
639
 
@@ -671,20 +691,33 @@ probs = ck.estimate_probabilities(results)
671
691
  `run()` and `run_cut_circuit()` take `qubits` in the same way, and hand back the
672
692
  distribution rather than expectation values.
673
693
 
674
- This costs `2**k` values for `k` qubits but no extra circuits, since the Z observables it
675
- needs all commute. See
676
- [the derivation](https://jooniv.github.io/QCut/theory/Probability_reconstruction.html).
694
+ The whole distribution needs one measurement setting, so the experiment is the size it
695
+ would have been for a single observable however many qubits are asked for. See
696
+ [the derivation](https://jooniv.github.io/QCut/theory/Probability_reconstruction.html)
697
+ for how the distribution is reconstructed.
698
+
699
+ The result is a mapping, so it indexes and plots like a dict, and carries three views:
700
+
701
+ ```python
702
+ probs["00"] # 0.8658
703
+ probs.quasi_probabilities() # the same values, as a plain dict
704
+ probs.nearest_probabilities() # closest true distribution, negatives projected away
705
+ probs.counts() # scaled by the shots the experiment ran at
706
+ probs.counts(shots=1000) # or by any other shots
707
+ ```
677
708
 
678
- The result is a dict, so it indexes and plots like one, and carries three views:
709
+ The three dict views report, by default, the ten most likely bitstrings. Pass `top` for a different
710
+ number, or `top=None` for all of them:
679
711
 
680
712
  ```python
681
- probs['00'] # 0.8658
682
- probs.quasi_probabilities() # the same values, as a plain dict
683
- probs.nearest_probabilities() # closest true distribution, negatives projected away
684
- probs.counts() # scaled by the shots the experiment ran at
685
- probs.counts(shots=1000) # or by any other shots
713
+ probs.quasi_probabilities(top=50) # the fifty most likely
714
+ probs.counts(shots=1000, top=None) # the whole distribution, as before
686
715
  ```
687
716
 
717
+ Note that :code:`counts()` sums to :code:`shots` only with :code:`top=None` and
718
+ Only :code:`quasi_probabilities()` gets cheaper this way since the other two project onto the
719
+ nearest physical distribution first.
720
+
688
721
  Against the same circuit run whole:
689
722
 
690
723
  ```python
@@ -20,6 +20,7 @@ from QCut.execution.circuit_knitting import (
20
20
  run_cut_circuit,
21
21
  run_experiments,
22
22
  )
23
+ from QCut.execution.observables import ObservablesLike
23
24
  from QCut.execution.parallel import ParallelBackend
24
25
  from QCut.execution.postprocess import (
25
26
  estimate_expectation_values,
@@ -67,4 +68,5 @@ __all__ = [
67
68
  "JobEstimate",
68
69
  "RawResult",
69
70
  "CircuitResult",
71
+ "ObservablesLike",
70
72
  ]
@@ -7,9 +7,17 @@ from __future__ import annotations
7
7
  from typing import Iterable
8
8
 
9
9
  from qiskit import QuantumCircuit
10
+ from qiskit.primitives.containers.observables_array import ObservablesArray
10
11
  from qiskit.quantum_info import SparsePauliOp
11
12
 
12
13
  from QCut.cutlocation import CutLocation, SingleQubitCutLocation
14
+ from QCut.execution.observables import (
15
+ ObservablesLike,
16
+ ObservableSpec,
17
+ coerce_observables,
18
+ per_term_observables,
19
+ )
20
+ from QCut.execution.probabilities import _all_z_paulis_for_subset
13
21
  from QCut.options import CutOptions, resolve
14
22
 
15
23
 
@@ -122,7 +130,7 @@ class CutExperiment:
122
130
  map_qubit: dict[int, int],
123
131
  coefficients: Iterable[float],
124
132
  can_reconstruct_probabilities: bool = False,
125
- observables: SparsePauliOp | None = None,
133
+ observables: ObservablesLike | ObservableSpec | None = None,
126
134
  qubits: list[int] | None = None,
127
135
  backend=None,
128
136
  options: CutOptions | None = None,
@@ -131,6 +139,7 @@ class CutExperiment:
131
139
  qpd_bits: dict[tuple[int, int, int], tuple[int, int]] | None = None,
132
140
  gamma: float | None = None,
133
141
  optimal_gamma: float | None = None,
142
+ uncut_num_qubits: int | None = None,
134
143
  ) -> None:
135
144
  """Init.
136
145
 
@@ -150,6 +159,13 @@ class CutExperiment:
150
159
  many were dropped for going unwritten. Post-processing needs both: the first to
151
160
  find those bits without relying on how a backend reports its registers, and the
152
161
  second to restore the sign the dropped ones carried.
162
+
163
+ ``uncut_num_qubits`` is the width of the circuit before it was cut, which the
164
+ observables of a ``qubits`` experiment span. Only that width is kept, since the
165
+ observables themselves are built on demand -- see :attr:`observables`.
166
+
167
+ ``observables`` is taken the way qiskit's estimator takes them, and is kept as
168
+ an :class:`QCut.execution.observables.ObservableSpec`.
153
169
  """
154
170
 
155
171
  self.experiments = experiment_circuits
@@ -157,8 +173,11 @@ class CutExperiment:
157
173
  self.cut_locations = cut_locations
158
174
  self.map_qubit = map_qubit
159
175
  self.coefficients = coefficients
160
- self.observables = observables
176
+ self._observables = (
177
+ None if observables is None else coerce_observables(observables)
178
+ )
161
179
  self.qubits = qubits
180
+ self._uncut_num_qubits = uncut_num_qubits
162
181
  self.options = resolve(options)
163
182
  self._num_draws = num_draws
164
183
  self.plan = plan
@@ -167,6 +186,54 @@ class CutExperiment:
167
186
  self._optimal_gamma = optimal_gamma
168
187
  self._can_reconstruct_probabilities = can_reconstruct_probabilities
169
188
 
189
+ @property
190
+ def observable_spec(self) -> ObservableSpec | None:
191
+ """The observables and their terms together, with the weights between them.
192
+
193
+ An experiment built from ``qubits`` is built for every Pauli Z over them, and
194
+ there are ``2**k`` of those. They all share one measurement setting, so none of
195
+ them shapes a circuit, and reconstructing the distribution does not go through
196
+ them either, see :func:`QCut.execution.probabilities._separable_form`. So they
197
+ are built here, on demand, for whoever does want them: estimating them one at a
198
+ time with :func:`QCut.estimate_expectation_values` still works.
199
+
200
+ Raises:
201
+ ValueError: the experiment was given ``qubits`` but not the width they span,
202
+ so the observables cannot be reconstructed.
203
+ """
204
+ if self._observables is None and self.qubits is not None:
205
+ if self._uncut_num_qubits is None:
206
+ raise ValueError(
207
+ "this experiment carries qubits but not the width of the circuit "
208
+ "they came from, so its observables cannot be built. Pass "
209
+ "uncut_num_qubits, or the observables themselves."
210
+ )
211
+ self._observables = per_term_observables(
212
+ _all_z_paulis_for_subset(self._uncut_num_qubits, self.qubits)
213
+ )
214
+ return self._observables
215
+
216
+ @property
217
+ def observables(self) -> ObservablesArray | None:
218
+ """The observables this experiment estimates, as qiskit's own container.
219
+
220
+ Its shape is the shape of the expectation values that come back, so a single
221
+ observable is a zero-dimensional array and a list of ``n`` is ``(n,)``. Note
222
+ that this is not what the circuits measure. See :attr:`observable_terms`.
223
+ """
224
+ spec = self.observable_spec
225
+ return None if spec is None else spec.array
226
+
227
+ @property
228
+ def observable_terms(self) -> SparsePauliOp | None:
229
+ """The distinct Pauli terms the circuits measure, each appearing once.
230
+
231
+ An observable is a weighted sum of these, and separate observables share them,
232
+ so there are usually fewer terms than observables asked for.
233
+ """
234
+ spec = self.observable_spec
235
+ return None if spec is None else spec.terms
236
+
170
237
  def assign_parameters(
171
238
  self, parameters: dict, inplace=False
172
239
  ) -> CutExperiment | None:
@@ -202,7 +269,7 @@ class CutExperiment:
202
269
  backend=self.backend,
203
270
  map_qubit=self.map_qubit,
204
271
  coefficients=self.coefficients,
205
- observables=self.observables,
272
+ observables=self._observables,
206
273
  qubits=self.qubits,
207
274
  options=self.options,
208
275
  num_draws=self._num_draws,
@@ -211,6 +278,7 @@ class CutExperiment:
211
278
  gamma=self._gamma,
212
279
  optimal_gamma=self._optimal_gamma,
213
280
  can_reconstruct_probabilities=self._can_reconstruct_probabilities,
281
+ uncut_num_qubits=self._uncut_num_qubits,
214
282
  )
215
283
 
216
284
  @property
@@ -0,0 +1 @@
1
+ """Circuit preparation: locating cuts and splitting a circuit into subcircuits."""
@@ -0,0 +1 @@
1
+ """QCut error types."""
@@ -0,0 +1 @@
1
+ """Running subcircuit experiments and post-processing their results."""
@@ -8,7 +8,8 @@ import logging
8
8
  from collections import defaultdict
9
9
 
10
10
  from qiskit import QuantumCircuit, transpile
11
- from qiskit.circuit import Gate
11
+ from qiskit.circuit import Gate, Instruction
12
+ from qiskit.circuit.library import get_standard_gate_name_mapping
12
13
  from qiskit.transpiler import PassManager, Target
13
14
 
14
15
  from QCut.cutcircuit import CutCircuit, CutExperiment
@@ -96,11 +97,15 @@ def _add_block_gates(target, coupling_map, members: dict[str, list[str]]) -> set
96
97
  is free to hand the marker its qubits either way round. Qiskit can turn a ``cz`` the
97
98
  right way because it knows the gate is symmetric; a marker is opaque, so an
98
99
  unsupported orientation is a transpiler error rather than something it can fix.
100
+
101
+ Without a coupling map every pair is coupled, so the marker is declared global.
99
102
  """
100
- loci = {}
101
- for first, second in coupling_map.get_edges():
102
- loci[(first, second)] = None
103
- loci[(second, first)] = None
103
+ loci = None
104
+ if coupling_map is not None:
105
+ loci = {}
106
+ for first, second in coupling_map.get_edges():
107
+ loci[(first, second)] = None
108
+ loci[(second, first)] = None
104
109
  for name, group in members.items():
105
110
  target.add_instruction(
106
111
  Gate(num_qubits=len(group), name=name, params=[], label=name),
@@ -235,6 +240,40 @@ def _placeholder_gates(cut_circuit) -> dict[str, Gate]:
235
240
  return gates
236
241
 
237
242
 
243
+ def _target_of(backend) -> Target:
244
+ """A backend's target, read through the public ``target``.
245
+
246
+ Raises:
247
+ QCutError: the backend has no target to transpile for.
248
+ """
249
+ target = getattr(backend, "target", None)
250
+ if target is None:
251
+ raise QCutError(
252
+ f"{backend} has no target to transpile for. Pass a backend that has one."
253
+ )
254
+ return target
255
+
256
+
257
+ def _basis(target: Target) -> tuple[list[str], dict[str, Instruction]]:
258
+ """The operations a target names, and those of them qiskit would not recognise."""
259
+ standard = get_standard_gate_name_mapping()
260
+ names: set[str] = set()
261
+ custom: dict[str, Instruction] = {}
262
+ for operation in target.operations:
263
+ if not isinstance(operation, Instruction):
264
+ continue
265
+ names.add(operation.name)
266
+ if operation.name not in standard:
267
+ custom[operation.name] = operation
268
+ return sorted(names), custom
269
+
270
+
271
+ def has_topology(backend) -> bool:
272
+ """Whether running on ``backend`` needs its circuits transpiled first."""
273
+ target = getattr(backend, "target", None)
274
+ return target is not None and target.build_coupling_map() is not None
275
+
276
+
238
277
  def _iqm_transpiler_for(backend):
239
278
  """Return IQM's transpiler if it is installed and ``backend`` is one of its own.
240
279
 
@@ -312,27 +351,16 @@ def transpile_subcircuits(
312
351
  # the multi-qubit operation it is rather than as unrelated single-qubit ones.
313
352
  spans, block_members = _block_spans(cut_circuit)
314
353
 
315
- target = Target()
316
-
317
- try:
318
- basis_gates = list(
319
- {
320
- i[0].name
321
- for i in backend._target.instructions
322
- if isinstance(i[0].name, str)
323
- }
324
- )
325
-
326
- except Exception as e:
327
- raise ValueError(f"Error accessing backend target instructions: {e}")
328
-
329
- target = target.from_configuration(
354
+ backend_target = _target_of(backend)
355
+ coupling_map = backend_target.build_coupling_map()
356
+ basis_gates, backend_gates = _basis(backend_target)
357
+ target = Target.from_configuration(
330
358
  num_qubits=backend.num_qubits,
331
- coupling_map=backend._coupling_map,
359
+ coupling_map=coupling_map,
332
360
  basis_gates=basis_gates + list(custom_gates.keys()),
333
- custom_name_mapping=custom_gates,
361
+ custom_name_mapping={**backend_gates, **custom_gates},
334
362
  )
335
- block_names = _add_block_gates(target, backend._coupling_map, block_members)
363
+ block_names = _add_block_gates(target, coupling_map, block_members)
336
364
 
337
365
  # Fenced first: a placeholder is a single-qubit gate as far as the transpiler is
338
366
  # concerned, so without barriers it gets commuted past the others and the experiment
@@ -479,7 +507,7 @@ def transpile_experiments(
479
507
  cut_locations=cut_experiment.cut_locations,
480
508
  map_qubit=cut_experiment.map_qubit,
481
509
  coefficients=cut_experiment.coefficients,
482
- observables=cut_experiment.observables,
510
+ observables=cut_experiment._observables,
483
511
  qubits=cut_experiment.qubits,
484
512
  options=cut_experiment.options,
485
513
  backend=backend,
@@ -488,7 +516,8 @@ def transpile_experiments(
488
516
  qpd_bits=cut_experiment.qpd_bits,
489
517
  gamma=cut_experiment.gamma,
490
518
  optimal_gamma=cut_experiment.optimal_gamma,
491
- can_reconstruct_probabilities=cut_experiment.qubits is not None,
519
+ can_reconstruct_probabilities=cut_experiment.can_reconstruct_probabilities,
520
+ uncut_num_qubits=cut_experiment._uncut_num_qubits,
492
521
  )
493
522
 
494
523
 
@@ -550,20 +579,17 @@ def transpile_circuits(
550
579
  for circuit in circuits
551
580
  ]
552
581
 
553
- # A simulator has no target to build one from, and needs none: it takes the
554
- # circuits as they are, so it is handed itself instead.
582
+ # An ideal simulator has no topology to build a target from, and needs none: it
583
+ # takes the circuits as they are, so it is handed itself instead.
555
584
  target = None
556
- if getattr(backend, "_target", None) is not None:
557
- target = Target().from_configuration(
585
+ if has_topology(backend):
586
+ backend_target = _target_of(backend)
587
+ basis_gates, backend_gates = _basis(backend_target)
588
+ target = Target.from_configuration(
558
589
  num_qubits=backend.num_qubits,
559
- coupling_map=backend._coupling_map,
560
- basis_gates=sorted(
561
- {
562
- item[0].name
563
- for item in backend._target.instructions
564
- if isinstance(item[0].name, str)
565
- }
566
- ),
590
+ coupling_map=backend_target.build_coupling_map(),
591
+ basis_gates=basis_gates,
592
+ custom_name_mapping=backend_gates,
567
593
  )
568
594
 
569
595
  return [