QCut 2.3.0__tar.gz → 2.4.0__tar.gz

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

@@ -2,6 +2,27 @@
 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**
 =================
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: QCut
-Version: 2.3.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@csc.fi>, FiQCI <servicedesk@csc.fi>
 License:                                  Apache License
@@ -496,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
 
@@ -565,10 +565,23 @@ 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
@@ -591,13 +604,18 @@ Exact for non-cummunicating runs. Runs whose wire cuts communicate get executed
 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)
 )
 ```
@@ -681,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.
@@ -696,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.3.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",