QCut 2.2.0__tar.gz → 2.4.0__tar.gz

{qcut-2.2.0 → qcut-2.4.0}/CHANGELOG.rst

@@ -2,6 +2,58 @@
 Changelog
 =========
 
+**Version 2.4.0**
+=================
+
+Submitting without blocking
+---------------------------
+
+- New :code:`submit_experiments()`, now the recommended way to run an experiment. It
+  takes the same arguments as :code:`run_experiments()` and returns a :code:`QCutJob`
+  once everything is submitted, without waiting for results. Its :code:`job_ids()`,
+  :code:`status()`, :code:`statuses()`, :code:`done()`, :code:`cancel()` and
+  :code:`result()` follow Qiskit's job interface, and :code:`partial_results()` reports
+  each batch's wave, job id, status, circuit and shot count, and result once it is in.
+- :code:`run_experiments()` is now :code:`submit_experiments(...).result()`. Its
+  signature and return value are unchanged.
+- Experiments whose wire cuts communicate return just as quickly. Wave zero is
+  submitted before :code:`submit_experiments()` returns, and a thread of the job's own
+  submits each later wave as soon as the one before it is in.
+- A target refusing a batch part-way through no longer loses the jobs already queued.
+  Nothing after it is submitted, the job reports :code:`ERROR`, and :code:`result()`
+  raises the refusal.
+
+**Version 2.3.0**
+=================
+
+Remove Qiskit-Aer dependency
+----------------------------
+
+- :code:`run()` and :code:`run_cut_circuit()` no longer default to :code:`AerSimulator()`;
+  pass a backend or sampler. :code:`qiskit-aer` is no longer installed with QCut, so
+  install it separately to simulate.
+- :code:`transpile_subcircuits()` and :code:`transpile_experiments()` read a backend's
+  public :code:`target` rather than :code:`_target`, which Aer never fills in. Transpiling
+  for :code:`AerSimulator` works, and :code:`run_cut_circuit()` transpiles only for a
+  backend with a coupling map.
+
+Deduplicated experiment circuits
+--------------------------------
+
+- A run now submits each *distinct* experiment circuit once and shares its result with
+  every slot it fills.
+- :code:`shots` still means shots per circuit, so a run spends that many on each
+  distinct circuit and the total drops by the same factor. What the old total bought
+  was re-measuring circuits already measured. Sharing a sample between groups leaves the estimate unbiased,
+  since the groups are summed rather than multiplied.
+- :code:`estimate_run()` counts the circuits and shots that are actually submitted, so
+  it still matches the run exactly.
+- :code:`CutOptions(deduplicate=False)` restores one submission per slot.
+  :code:`CutExperiment.num_circuits` is unchanged: it still counts the circuits the
+  decomposition calls for.
+- Experiments whose wire cuts communicate are unaffected for now. Their first wave
+  already shares circuits between the groups that differ only in the label they answer.
+
 **Version 2.2.0**
 =================
 

{qcut-2.2.0 → qcut-2.4.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: QCut
-Version: 2.2.0
+Version: 2.4.0
 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.
-Author-email: Joonas Nivala <joonas.nivala@gmail.com>
+Author-email: Joonas Nivala <joonas.nivala@csc.fi>, FiQCI <servicedesk@csc.fi>
 License:                                  Apache License
                                    Version 2.0, January 2004
                                 http://www.apache.org/licenses/
@@ -205,10 +205,10 @@ License:                                  Apache License
            See the License for the specific language governing permissions and
            limitations under the License.
         
-Project-URL: homepage, https://github.com/JooNiv/QCut
-Project-URL: documentation, https://jooniv.github.io/QCut/
-Project-URL: repository, https://github.com/JooNiv/QCut.git
-Project-URL: changelog, https://github.com/JooNiv/QCut/blob/main/CHANGELOG.rst
+Project-URL: homepage, https://github.com/FiQCI/QCut
+Project-URL: documentation, https://fiqci.fi/QCut/
+Project-URL: repository, https://github.com/FiQCI/QCut.git
+Project-URL: changelog, https://github.com/FiQCI/QCut/blob/main/CHANGELOG.rst
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -219,7 +219,6 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: qiskit<3.0,>=1.1
 Requires-Dist: numpy
-Requires-Dist: qiskit-aer<0.18
 Requires-Dist: pymetis==2025.2.2
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
@@ -258,7 +257,7 @@ Dynamic: license-file
 
 # QCut
 
-![QCut Banner](docs/_static/images/logos/qcut-banner.png)
+<img src="docs/_static/images/diagram/qcut-diagram-left-logo.png" alt="QCut Diagram" width="1000">
 
 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/)).
 
@@ -281,6 +280,8 @@ uv add QCut
 
 If using other than the default Qiskit version (newest) it is recommended to install Qiskit first before installing QCut.
 
+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`.
+
 **IQM hardware and fake backends:**
 
 ```bash
@@ -297,6 +298,7 @@ After installing you can simply import what you need:
 
 ```python
 from iqm.qiskit_iqm import IQMFakeAdonis
+
 backend = IQMFakeAdonis()
 ```
 
@@ -342,7 +344,10 @@ from qiskit import QuantumCircuit, transpile
 from qiskit.circuit.library import CXGate
 from qiskit.quantum_info import SparsePauliOp
 from qiskit_aer import AerSimulator
-from qiskit.primitives import StatevectorEstimator as Estimator, BackendEstimatorV2 as BackendEstimator
+from qiskit.primitives import (
+    StatevectorEstimator as Estimator,
+    BackendEstimatorV2 as BackendEstimator,
+)
 from iqm.qiskit_iqm import IQMFakeAdonis
 ```
 
@@ -352,11 +357,11 @@ from iqm.qiskit_iqm import IQMFakeAdonis
 circuit = QuantumCircuit(5)
 
 for qubit in range(5):
-    circuit.ry(0.4 + 0.3*qubit, qubit)
-circuit.cx(0,1)
-circuit.cx(1,2)
-circuit.cx(2,3)
-circuit.cx(3,4)
+    circuit.ry(0.4 + 0.3 * qubit, qubit)
+circuit.cx(0, 1)
+circuit.cx(1, 2)
+circuit.cx(2, 3)
+circuit.cx(3, 4)
 
 circuit.draw("mpl")
 ```
@@ -371,12 +376,12 @@ Note that here we don't insert any measurements. Measurements will be automatica
 marked_circuit = QuantumCircuit(5)
 
 for qubit in range(5):
-    marked_circuit.ry(0.4 + 0.3*qubit, qubit)
-marked_circuit.cx(0,1)
+    marked_circuit.ry(0.4 + 0.3 * qubit, qubit)
+marked_circuit.cx(0, 1)
 marked_circuit.append(**cutGate(CXGate(), 1, 2))
-marked_circuit.cx(2,3)
+marked_circuit.cx(2, 3)
 marked_circuit.append(cut(), [3])
-marked_circuit.cx(3,4)
+marked_circuit.cx(3, 4)
 
 marked_circuit.decompose(gates_to_decompose=["CutGate"]).draw("mpl")
 ```
@@ -491,7 +496,7 @@ print(block.gamma, local.gamma, local.optimal_gamma)
 `7.0 16.0 7.0`
 
 Those cuts run in waves, since one side has to be measured before the other can prepare
-what it measured. `run_experiments()` handles that itself.
+what it measured. `submit_experiments()` handles that itself.
 
 ### Options
 
@@ -527,8 +532,8 @@ finder's own options and how it chooses.
 Two helpers, `transpile_subcircuits()` and `transpile_experiments()` , differing in when they run:
 
 ```python
-fake = IQMFakeAdonis() #noisy
-sim = AerSimulator() #ideal
+fake = IQMFakeAdonis()  # noisy
+sim = AerSimulator()  # ideal
 ```
 
 `transpile_circuits()` does whichever of the two the thing it is given calls for. Each
@@ -560,33 +565,57 @@ routed in for you. See
 ## Execution
 
 ```python
-results = ck.run_experiments(cut_experiment, backend=fake)
-expectation_values = ck.estimate_expectation_values(results)
+job = ck.submit_experiments(cut_experiment, backend=fake)
+expectation_values = ck.estimate_expectation_values(job.result())
+```
+
+`submit_experiments()` returns a `QCutJob` as soon as everything is submitted, and
+`result()` waits for the results. The job is shaped like a Qiskit job, so it can be
+checked on while the run is under way:
+
+```python
+job.job_ids()  # every backend job, in submission order
+job.status()  # one JobStatus for the whole experiment
+job.partial_results()  # per batch: wave, job id, status, circuits, shots, result
 ```
 
+`run_experiments()` takes the same arguments and is the same as
+`submit_experiments(...).result()`.
+
 The cost of an experiment run can be checked before submission:
 
 ```python
 print(ck.estimate_run(cut_experiment, shots=4096, max_batch_size=40))
 ```
 
-`Experiment will run 144 circuits in 4 jobs with a total of 589824 shots. See the returned object for the breakdown.`
+`Experiment will run 31 circuits in 1 jobs with a total of 126976 shots. See the returned object for the breakdown.`
 
 ```python
-{'job1': JobEstimate(circuits=40, shots=4096), 'job2': JobEstimate(circuits=40, shots=4096), ...}
+{"job1": JobEstimate(circuits=31, shots=4096)}
 ```
 
+31 circuits, not the 144 the decomposition calls for: a subcircuit's experiment circuit
+depends only on the QPD terms of the cuts touching it and on the measurement setting
+over its own qubits, so most of them repeat. Each distinct one is submitted once and its
+result shared, which is where the saving comes from. `shots` still means shots per
+circuit. Pass `CutOptions(deduplicate=False)` to submit one circuit per slot instead.
+
 Exact for non-cummunicating runs. Runs whose wire cuts communicate get executed in waves so that
 each wave after the first spends its shots on what the one before it measured. For these jobs
 the circuit count is exact and job and shot counts are estimates.
 
+The job submits those waves itself. The first goes out before `submit_experiments()`
+returns, and a thread of the job's own submits each later one as soon as the one before
+it is in, so nothing has to keep polling for the run to move on. `job.cancel()` cancels
+what is still queued and submits no further waves.
+
 `backend` takes a Qiskit backend, a V2 sampler, or anything else shaped like a backend,
 which is what lets e.g. [fiqci-ems](https://github.com/FiQCI/fiqci-ems) run the experiment:
 
 ```python
 from fiqci.ems import FiQCISampler
 
-results = ck.run_experiments(
+job = ck.submit_experiments(
     cut_experiment, backend=FiQCISampler(backend, mitigation_level=1)
 )
 ```
@@ -604,8 +633,11 @@ Comparing against the exact and noisy expectation values of the original circuit
 
 ```python
 estimator = Estimator()
-exact_expvals = [e.data.evs for e in
-    estimator.run([(x) for x in zip([circuit] * len(observables), observables)]).result()
+exact_expvals = [
+    e.data.evs
+    for e in estimator.run(
+        [(x) for x in zip([circuit] * len(observables), observables)]
+    ).result()
 ]
 
 tr = transpile(circuit, backend=fake)
@@ -615,8 +647,11 @@ tr_obs_separate = [
 ]
 
 fake_estimator = BackendEstimator(backend=fake)
-exps = [e.data.evs for e in
-    fake_estimator.run([(x) for x in zip([tr] * len(tr_obs_separate), tr_obs_separate)]).result()
+exps = [
+    e.data.evs
+    for e in fake_estimator.run(
+        [(x) for x in zip([tr] * len(tr_obs_separate), tr_obs_separate)]
+    ).result()
 ]
 ```
 
@@ -664,12 +699,16 @@ instead of `observables`:
 
 ```python
 cut_experiment = ck.get_experiment_circuits(cut_circuit, qubits=[0, 1])
-results = ck.run_experiments(cut_experiment, shots=4096, backend=sim)
+job = ck.submit_experiments(cut_experiment, shots=4096, backend=sim)
 
-probs = ck.estimate_probabilities(results)
+probs = ck.estimate_probabilities(job.result())
+print(probs)
 ```
 
-`{'00': 0.8658, '01': -0.0024, '10': 0.1041, '11': 0.0324}`
+`QuasiProbabilities({'00': 0.8658, '01': -0.0024, '10': 0.1041, '11': 0.0324})`
+
+The bitstrings are read with the first of the chosen qubits as the rightmost character, so
+with `qubits=[2, 0]` qubit 2 is the last character and qubit 0 the first.
 
 `run()` and `run_cut_circuit()` take `qubits` in the same way, and hand back the
 distribution rather than expectation values.
@@ -679,27 +718,17 @@ would have been for a single observable however many qubits are asked for. See
 [the derivation](https://jooniv.github.io/QCut/theory/Probability_reconstruction.html)
 for how the distribution is reconstructed.
 
-The result is a mapping, so it indexes and plots like a dict, and carries three views:
-
-```python
-probs['00']                     # 0.8658
-probs.quasi_probabilities()     # the same values, as a plain dict
-probs.nearest_probabilities()   # closest true distribution, negatives projected away
-probs.counts()                  # scaled by the shots the experiment ran at
-probs.counts(shots=1000)        # or by any other shots
-```
-
-The three dict views report, by default, the ten most likely bitstrings. Pass `top` for a different
-number, or `top=None` for all of them:
+The distribution is never built as a table of `2**k` values unless asked for, so the
+recommended way to read it is `top()`, which finds the most likely bitstrings directly:
 
 ```python
-probs.quasi_probabilities(top=50)      # the fifty most likely
-probs.counts(shots=1000, top=None)     # the whole distribution, as before
+probs.top(10)  # {'00': 0.8658, '10': 0.1041, '11': 0.0324, '01': -0.0024}
 ```
 
-Note that :code:`counts()` sums to :code:`shots` only with :code:`top=None` and
-Only :code:`quasi_probabilities()` gets cheaper this way since the other two project onto the
-nearest physical distribution first.
+`probability_of()` and `marginal()` give one bitstring or a subset of the qubits.
+`nearest_probabilities()` and `counts()` give the closest true distribution, as
+probabilities or scaled to shots. They report the ten most likely bitstrings, or all of
+them with `top=None`.
 
 Against the same circuit run whole:
 

{qcut-2.2.0 → qcut-2.4.0}/QCut/__init__.py

@@ -19,7 +19,9 @@ from QCut.execution.circuit_knitting import (
     run,
     run_cut_circuit,
     run_experiments,
+    submit_experiments,
 )
+from QCut.execution.job import PartialBatch, QCutJob
 from QCut.execution.observables import ObservablesLike
 from QCut.execution.parallel import ParallelBackend
 from QCut.execution.postprocess import (
@@ -53,6 +55,9 @@ __all__ = [
     "run",
     "run_cut_circuit",
     "run_experiments",
+    "submit_experiments",
+    "QCutJob",
+    "PartialBatch",
     "cut",
     "cutCZ",
     "cutSWAP",

{qcut-2.2.0 → qcut-2.4.0}/QCut/execution/backend_utility.py

@@ -8,7 +8,8 @@ import logging
 from collections import defaultdict
 
 from qiskit import QuantumCircuit, transpile
-from qiskit.circuit import Gate
+from qiskit.circuit import Gate, Instruction
+from qiskit.circuit.library import get_standard_gate_name_mapping
 from qiskit.transpiler import PassManager, Target
 
 from QCut.cutcircuit import CutCircuit, CutExperiment
@@ -96,11 +97,15 @@ def _add_block_gates(target, coupling_map, members: dict[str, list[str]]) -> set
     is free to hand the marker its qubits either way round. Qiskit can turn a ``cz`` the
     right way because it knows the gate is symmetric; a marker is opaque, so an
     unsupported orientation is a transpiler error rather than something it can fix.
+
+    Without a coupling map every pair is coupled, so the marker is declared global.
     """
-    loci = {}
-    for first, second in coupling_map.get_edges():
-        loci[(first, second)] = None
-        loci[(second, first)] = None
+    loci = None
+    if coupling_map is not None:
+        loci = {}
+        for first, second in coupling_map.get_edges():
+            loci[(first, second)] = None
+            loci[(second, first)] = None
     for name, group in members.items():
         target.add_instruction(
             Gate(num_qubits=len(group), name=name, params=[], label=name),
@@ -235,6 +240,40 @@ def _placeholder_gates(cut_circuit) -> dict[str, Gate]:
     return gates
 
 
+def _target_of(backend) -> Target:
+    """A backend's target, read through the public ``target``.
+
+    Raises:
+        QCutError: the backend has no target to transpile for.
+    """
+    target = getattr(backend, "target", None)
+    if target is None:
+        raise QCutError(
+            f"{backend} has no target to transpile for. Pass a backend that has one."
+        )
+    return target
+
+
+def _basis(target: Target) -> tuple[list[str], dict[str, Instruction]]:
+    """The operations a target names, and those of them qiskit would not recognise."""
+    standard = get_standard_gate_name_mapping()
+    names: set[str] = set()
+    custom: dict[str, Instruction] = {}
+    for operation in target.operations:
+        if not isinstance(operation, Instruction):
+            continue
+        names.add(operation.name)
+        if operation.name not in standard:
+            custom[operation.name] = operation
+    return sorted(names), custom
+
+
+def has_topology(backend) -> bool:
+    """Whether running on ``backend`` needs its circuits transpiled first."""
+    target = getattr(backend, "target", None)
+    return target is not None and target.build_coupling_map() is not None
+
+
 def _iqm_transpiler_for(backend):
     """Return IQM's transpiler if it is installed and ``backend`` is one of its own.
 
@@ -312,27 +351,16 @@ def transpile_subcircuits(
     # the multi-qubit operation it is rather than as unrelated single-qubit ones.
     spans, block_members = _block_spans(cut_circuit)
 
-    target = Target()
-
-    try:
-        basis_gates = list(
-            {
-                i[0].name
-                for i in backend._target.instructions
-                if isinstance(i[0].name, str)
-            }
-        )
-
-    except Exception as e:
-        raise ValueError(f"Error accessing backend target instructions: {e}")
-
-    target = target.from_configuration(
+    backend_target = _target_of(backend)
+    coupling_map = backend_target.build_coupling_map()
+    basis_gates, backend_gates = _basis(backend_target)
+    target = Target.from_configuration(
         num_qubits=backend.num_qubits,
-        coupling_map=backend._coupling_map,
+        coupling_map=coupling_map,
         basis_gates=basis_gates + list(custom_gates.keys()),
-        custom_name_mapping=custom_gates,
+        custom_name_mapping={**backend_gates, **custom_gates},
     )
-    block_names = _add_block_gates(target, backend._coupling_map, block_members)
+    block_names = _add_block_gates(target, coupling_map, block_members)
 
     # Fenced first: a placeholder is a single-qubit gate as far as the transpiler is
     # concerned, so without barriers it gets commuted past the others and the experiment
@@ -551,20 +579,17 @@ def transpile_circuits(
             for circuit in circuits
         ]
 
-    # A simulator has no target to build one from, and needs none: it takes the
-    # circuits as they are, so it is handed itself instead.
+    # An ideal simulator has no topology to build a target from, and needs none: it
+    # takes the circuits as they are, so it is handed itself instead.
     target = None
-    if getattr(backend, "_target", None) is not None:
-        target = Target().from_configuration(
+    if has_topology(backend):
+        backend_target = _target_of(backend)
+        basis_gates, backend_gates = _basis(backend_target)
+        target = Target.from_configuration(
             num_qubits=backend.num_qubits,
-            coupling_map=backend._coupling_map,
-            basis_gates=sorted(
-                {
-                    item[0].name
-                    for item in backend._target.instructions
-                    if isinstance(item[0].name, str)
-                }
-            ),
+            coupling_map=backend_target.build_coupling_map(),
+            basis_gates=basis_gates,
+            custom_name_mapping=backend_gates,
         )
 
     return [