qiskit-resume 0.2.0__tar.gz

qiskit_resume-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jihoon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

qiskit_resume-0.2.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: qiskit-resume
+Version: 0.2.0
+Summary: Record & replay layer that lets any Qiskit Primitives workflow resume after interruption without re-spending QPU time.
+Author: Jihoon
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/set3523/Qiskit-resume
+Project-URL: Issues, https://github.com/set3523/Qiskit-resume/issues
+Keywords: qiskit,quantum,checkpoint,resume,ibm-quantum,vqe,qaoa
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: qiskit>=1.4
+Requires-Dist: numpy>=1.23
+Provides-Extra: ibm
+Requires-Dist: qiskit-ibm-runtime>=0.30; extra == "ibm"
+Provides-Extra: examples
+Requires-Dist: qiskit-algorithms>=0.3; extra == "examples"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: scipy; extra == "dev"
+Dynamic: license-file
+
+# qiskit-resume
+
+**Run any Qiskit Primitives workflow so that it can be interrupted and resumed — without paying for the same QPU time twice.**
+
+If your script stops (quota used up, laptop closed, network, Ctrl+C, crash), run the same command again:
+
+- finished calls are **replayed instantly** from a local `.qresume` file,
+- a job that was still running on IBM is **reconnected**, not resubmitted,
+- only new work uses the QPU.
+
+It works for any algorithm (VQE, QAOA, sampling sweeps, `qiskit_algorithms`, your own loops) because it
+records *calls*, not algorithm state: on a rerun your code runs again from the top, gets the recorded
+answers, rebuilds its own state (optimizer memory included) and continues at the first unrecorded call.
+Built first for the IBM Quantum Open Plan (10 QPU minutes per rolling 28 days).
+
+Status: 0.x - tested on simulators and on real IBM hardware ([results](#test-results-on-real-ibm-hardware));
+the file format may still change between minor versions.
+
+## Install
+
+```bash
+pip install qiskit-resume            # Qiskit >= 1.4 (tested 1.4 and 2.6), Python >= 3.10
+pip install "qiskit-resume[ibm]"     # + qiskit-ibm-runtime, for IBM hardware
+```
+
+## Add it to your script
+
+Four changes; the rest of the script stays as it is.
+
+**Before** (plain Qiskit):
+
+```python
+from qiskit_ibm_runtime import QiskitRuntimeService, EstimatorV2
+from qiskit.transpiler import generate_preset_pass_manager
+
+service = QiskitRuntimeService()
+backend = service.least_busy(operational=True, simulator=False)
+pm = generate_preset_pass_manager(optimization_level=1, backend=backend)
+estimator = EstimatorV2(mode=backend)
+
+isa = pm.run(ansatz)
+theta0 = np.random.default_rng().uniform(-np.pi, np.pi, ansatz.num_parameters)
+res = minimize(lambda x: float(estimator.run([(isa, H.apply_layout(isa.layout), x)]).result()[0].data.evs),
+               theta0, method="COBYLA")
+```
+
+**After**:
+
+```python
+from qiskit_ibm_runtime import EstimatorV2
+import qiskit_resume as resume
+
+with resume.resume_run("vqe.qresume"):                         # 1. everything runs inside this block
+    backend = resume.backend()                                  # 2. device chosen once, reused on reruns
+    pm = resume.pass_manager(backend, optimization_level=1)     # 3. recorded, fixed-seed transpile
+    estimator = resume.wrap(EstimatorV2(mode=backend))         # 4. wrap every Estimator / Sampler
+
+    isa = pm.run(ansatz)
+    theta0 = resume.rng("init").uniform(-np.pi, np.pi, ansatz.num_parameters)  # 5. randomness that replays
+    res = minimize(lambda x: float(estimator.run([(isa, H.apply_layout(isa.layout), x)]).result()[0].data.evs),
+                   theta0, method="COBYLA")
+```
+
+Then check it, without using QPU time or an account:
+
+```bash
+qresume selftest my_script.py -- <your script arguments>
+```
+
+`selftest` kills and resumes the script at several points with synthetic results and reports `OK: safe to
+resume` or the exact call (and source line) that would not resume. Run it after every change to the script.
+
+### Rules (for people and for AI assistants applying this)
+
+1. Put the code after the imports inside `with resume.resume_run("<name>.qresume"):` (primitive calls,
+   `resume.rng`, `resume.seed_for` and `resume.backend` must be inside). One file per experiment, relative
+   to the working directory; rerunning with the same file continues it, a new name starts from scratch.
+2. Wrap **every** Estimator and Sampler with `resume.wrap(...)` (`EstimatorV2`/`SamplerV2`, the newer
+   `qiskit_ibm_runtime` `Estimator`/`Sampler`, or local `StatevectorEstimator`/`StatevectorSampler`).
+   Library algorithms (`qiskit_algorithms.VQE`, `QAOA`, `VQD`, `ComputeUncompute`, ...) get the wrapped
+   objects passed in.
+3. Replace `generate_preset_pass_manager(...)` with `resume.pass_manager(backend, ...)` (same arguments).
+   For a simulator without a backend: `resume.pass_manager(optimization_level=1, basis_gates=[...])`.
+   It works wherever a pass manager is accepted (e.g. `QAOA(..., transpiler=pm)`).
+4. On IBM, get the device with `resume.backend(service)` (or `resume.backend(service, name="ibm_...")`)
+   instead of `service.least_busy(...)`, so a rerun uses the same device. Extra filters stay as keyword
+   arguments: `resume.backend(service, min_num_qubits=5)`.
+5. Replace unseeded randomness that feeds the computation: `np.random.default_rng()` ->
+   `resume.rng("purpose")`; `np.random.rand(k)` -> `resume.rng("purpose").random(k)`; `random.random()` ->
+   `resume.rng("purpose").random()`; a random `int` seed (`seed=random.randint(...)`) ->
+   `resume.seed_for("purpose")`. `resume.rng("x")` returns the same generator for the same name, so it is
+   safe inside loops. Use one name per purpose. Seeded code (`default_rng(42)`) can stay.
+6. Do not change anything else (removing imports that became unused is fine). Run `qresume selftest` and
+   fix what it reports. Library-internal randomness (e.g. SPSA in `qiskit_algorithms`) needs nothing.
+7. Optional: decorate a slow, deterministic classical function with `@resume.wrap` so reruns skip it
+   (classical code otherwise reruns on every replay - correct, just slower). The end-of-run report lists
+   slow sections worth wrapping.
+
+## API
+
+| call | what it does |
+|---|---|
+| `resume.resume_run(path, **settings)` | the experiment context; settings: `qpu_budget_s`, `job_wait_timeout_s`, `job_max_retries`, `on_divergence`, `on_backend_change`, `seed`, `force`, `log_calls`, ... |
+| `resume.wrap(estimator_or_sampler)` | records each call: question hash, IBM job id (before waiting), result, QPU seconds; replays/reconnects on rerun |
+| `resume.pass_manager(backend, **preset_args)` | recorded preset pass manager with a fixed `seed_transpiler`; same circuit on every rerun |
+| `resume.wrap(pm, backend=backend)` | the same for a pass manager you built yourself |
+| `resume.backend(service=None, name=None)` | the experiment's IBM device: least busy (or `name`) on the first run, the recorded one afterwards |
+| `resume.rng(name=None, *, seed=None)` | numpy `Generator` that replays: one generator per name (order-independent, safe in loops), a new one per unnamed call (by call order), or from an explicit seed |
+| `resume.seed_for(name)` / `resume.seed` | stable `int` seed per name / the experiment seed |
+| `@resume.wrap` on a function | records a slow, side-effect-free function's return value per arguments |
+| `run.snapshot({...})` / `run.load_snapshot()` | optional: skip replaying the start of a very long run |
+
+Other behaviour: changed code is detected and reported (`on_divergence="stop"` to stop instead of
+continuing); a device change is detected (`on_backend_change="stop"`); `qpu_budget_s` stops cleanly before
+the job that would exceed it; global `random`/`numpy` and `qiskit_algorithms.algorithm_globals` are seeded.
+
+## Before spending QPU time
+
+```bash
+qresume selftest my_script.py -- my.qresume      # crash/resume at several points with synthetic results (no QPU)
+qresume check my_script.py --file my.qresume -- my.qresume   # can this file continue? (no IBM contact)
+qresume status my.qresume                        # calls, snapshots, device, QPU used, warnings
+```
+
+Other commands: `copy` (consistent copy while running), `export`, `quota`, `fork` (branch at a
+snapshot), `pack`/`unpack`, `compact`.
+
+## See it work
+
+[`examples/crash_and_resume.py`](https://github.com/set3523/Qiskit-resume/blob/master/examples/crash_and_resume.py) takes a plain Qiskit workload
+(VQE, QAOA, VQD from `qiskit_algorithms`, unmodified), wraps it, **kills the process part way**, runs it
+again and checks the result equals an uninterrupted run, logging every call to the console:
+
+```bash
+git clone https://github.com/set3523/Qiskit-resume && cd Qiskit-resume/examples
+pip install "qiskit-resume[examples]" scipy
+python crash_and_resume.py standard/qaoa_maxcut.py --kill-at-call 100 --compare
+```
+
+## Test results on real IBM hardware
+
+ibm_kingston, IBM Quantum Open Plan, 2026-10-24/25. Reproduce with
+[`examples/ibm/`](https://github.com/set3523/Qiskit-resume/tree/master/examples/ibm).
+
+| # | What was checked | Workload | Result |
+|---|---|---|---|
+| 1 | Estimator loop, hard kill, rerun: recorded calls replay from the file | VQE (EstimatorV2 + COBYLA) | PASS |
+| 2 | Rerun reconnects to the job submitted before the kill (still running / already finished), no resubmission | VQE, QAOA, checks 6, 9 | PASS |
+| 3 | QPU budget stops the run before the job that would exceed it | VQE | PASS |
+| 4 | Sampler loop, hard kill, reconnect, run to completion | QAOA Max-Cut (SamplerV2 + COBYLA) | PASS |
+| 5 | Jobs with several pubs and parameter sweeps replay bit-for-bit | Estimator 2 pubs (broadcast), Sampler 2 circuits (sweep) | PASS |
+| 6 | Kill right after submit, rerun reconnects to the same job id | Estimator | PASS |
+| 7 | Wait timeout stops cleanly, rerun reconnects to the waiting job | Estimator | PASS |
+| 8 | Device change (ibm_kingston -> ibm_fez) stops before any submission | Estimator | PASS |
+| 9 | New client-side `Estimator`/`Sampler` (qiskit-ibm-runtime >= 0.50): reconnect and replay | Estimator + Sampler | PASS |
+| - | IBM-side job failure and automatic retry | - | not seen yet (tested with a fake service) |
+| - | Real quota-exhausted stop | - | not seen yet (tested with a fake service) |
+| - | Reconnect while the job is still QUEUED | - | not seen yet (queue was empty; same code path as above) |
+
+Observed QPU cost per job on ibm_kingston: Sampler about 2 s, Estimator about 11-13 s (default error mitigation).
+
+## Limits
+
+- A single circuit execution cannot be paused (quantum states can't be saved); interruption
+  granularity is one primitive call.
+- Code that is not deterministic in ways qiskit-resume can't seed (time, external data) may
+  diverge on replay — you'll be told where.
+- Calls not made through Primitives (`backend.run`, direct `Statevector` maths) are not recorded.
+
+## Documentation
+
+[DECISIONS](https://github.com/set3523/Qiskit-resume/blob/master/docs/DECISIONS.md) (why) ·
+[ARCHITECTURE](https://github.com/set3523/Qiskit-resume/blob/master/docs/ARCHITECTURE.md) (layers and flow) ·
+[CONTRACTS](https://github.com/set3523/Qiskit-resume/blob/master/docs/CONTRACTS.md) (every module's inputs/outputs)
+
+License: MIT

qiskit_resume-0.2.0/README.md

@@ -0,0 +1,176 @@
+# qiskit-resume
+
+**Run any Qiskit Primitives workflow so that it can be interrupted and resumed — without paying for the same QPU time twice.**
+
+If your script stops (quota used up, laptop closed, network, Ctrl+C, crash), run the same command again:
+
+- finished calls are **replayed instantly** from a local `.qresume` file,
+- a job that was still running on IBM is **reconnected**, not resubmitted,
+- only new work uses the QPU.
+
+It works for any algorithm (VQE, QAOA, sampling sweeps, `qiskit_algorithms`, your own loops) because it
+records *calls*, not algorithm state: on a rerun your code runs again from the top, gets the recorded
+answers, rebuilds its own state (optimizer memory included) and continues at the first unrecorded call.
+Built first for the IBM Quantum Open Plan (10 QPU minutes per rolling 28 days).
+
+Status: 0.x - tested on simulators and on real IBM hardware ([results](#test-results-on-real-ibm-hardware));
+the file format may still change between minor versions.
+
+## Install
+
+```bash
+pip install qiskit-resume            # Qiskit >= 1.4 (tested 1.4 and 2.6), Python >= 3.10
+pip install "qiskit-resume[ibm]"     # + qiskit-ibm-runtime, for IBM hardware
+```
+
+## Add it to your script
+
+Four changes; the rest of the script stays as it is.
+
+**Before** (plain Qiskit):
+
+```python
+from qiskit_ibm_runtime import QiskitRuntimeService, EstimatorV2
+from qiskit.transpiler import generate_preset_pass_manager
+
+service = QiskitRuntimeService()
+backend = service.least_busy(operational=True, simulator=False)
+pm = generate_preset_pass_manager(optimization_level=1, backend=backend)
+estimator = EstimatorV2(mode=backend)
+
+isa = pm.run(ansatz)
+theta0 = np.random.default_rng().uniform(-np.pi, np.pi, ansatz.num_parameters)
+res = minimize(lambda x: float(estimator.run([(isa, H.apply_layout(isa.layout), x)]).result()[0].data.evs),
+               theta0, method="COBYLA")
+```
+
+**After**:
+
+```python
+from qiskit_ibm_runtime import EstimatorV2
+import qiskit_resume as resume
+
+with resume.resume_run("vqe.qresume"):                         # 1. everything runs inside this block
+    backend = resume.backend()                                  # 2. device chosen once, reused on reruns
+    pm = resume.pass_manager(backend, optimization_level=1)     # 3. recorded, fixed-seed transpile
+    estimator = resume.wrap(EstimatorV2(mode=backend))         # 4. wrap every Estimator / Sampler
+
+    isa = pm.run(ansatz)
+    theta0 = resume.rng("init").uniform(-np.pi, np.pi, ansatz.num_parameters)  # 5. randomness that replays
+    res = minimize(lambda x: float(estimator.run([(isa, H.apply_layout(isa.layout), x)]).result()[0].data.evs),
+                   theta0, method="COBYLA")
+```
+
+Then check it, without using QPU time or an account:
+
+```bash
+qresume selftest my_script.py -- <your script arguments>
+```
+
+`selftest` kills and resumes the script at several points with synthetic results and reports `OK: safe to
+resume` or the exact call (and source line) that would not resume. Run it after every change to the script.
+
+### Rules (for people and for AI assistants applying this)
+
+1. Put the code after the imports inside `with resume.resume_run("<name>.qresume"):` (primitive calls,
+   `resume.rng`, `resume.seed_for` and `resume.backend` must be inside). One file per experiment, relative
+   to the working directory; rerunning with the same file continues it, a new name starts from scratch.
+2. Wrap **every** Estimator and Sampler with `resume.wrap(...)` (`EstimatorV2`/`SamplerV2`, the newer
+   `qiskit_ibm_runtime` `Estimator`/`Sampler`, or local `StatevectorEstimator`/`StatevectorSampler`).
+   Library algorithms (`qiskit_algorithms.VQE`, `QAOA`, `VQD`, `ComputeUncompute`, ...) get the wrapped
+   objects passed in.
+3. Replace `generate_preset_pass_manager(...)` with `resume.pass_manager(backend, ...)` (same arguments).
+   For a simulator without a backend: `resume.pass_manager(optimization_level=1, basis_gates=[...])`.
+   It works wherever a pass manager is accepted (e.g. `QAOA(..., transpiler=pm)`).
+4. On IBM, get the device with `resume.backend(service)` (or `resume.backend(service, name="ibm_...")`)
+   instead of `service.least_busy(...)`, so a rerun uses the same device. Extra filters stay as keyword
+   arguments: `resume.backend(service, min_num_qubits=5)`.
+5. Replace unseeded randomness that feeds the computation: `np.random.default_rng()` ->
+   `resume.rng("purpose")`; `np.random.rand(k)` -> `resume.rng("purpose").random(k)`; `random.random()` ->
+   `resume.rng("purpose").random()`; a random `int` seed (`seed=random.randint(...)`) ->
+   `resume.seed_for("purpose")`. `resume.rng("x")` returns the same generator for the same name, so it is
+   safe inside loops. Use one name per purpose. Seeded code (`default_rng(42)`) can stay.
+6. Do not change anything else (removing imports that became unused is fine). Run `qresume selftest` and
+   fix what it reports. Library-internal randomness (e.g. SPSA in `qiskit_algorithms`) needs nothing.
+7. Optional: decorate a slow, deterministic classical function with `@resume.wrap` so reruns skip it
+   (classical code otherwise reruns on every replay - correct, just slower). The end-of-run report lists
+   slow sections worth wrapping.
+
+## API
+
+| call | what it does |
+|---|---|
+| `resume.resume_run(path, **settings)` | the experiment context; settings: `qpu_budget_s`, `job_wait_timeout_s`, `job_max_retries`, `on_divergence`, `on_backend_change`, `seed`, `force`, `log_calls`, ... |
+| `resume.wrap(estimator_or_sampler)` | records each call: question hash, IBM job id (before waiting), result, QPU seconds; replays/reconnects on rerun |
+| `resume.pass_manager(backend, **preset_args)` | recorded preset pass manager with a fixed `seed_transpiler`; same circuit on every rerun |
+| `resume.wrap(pm, backend=backend)` | the same for a pass manager you built yourself |
+| `resume.backend(service=None, name=None)` | the experiment's IBM device: least busy (or `name`) on the first run, the recorded one afterwards |
+| `resume.rng(name=None, *, seed=None)` | numpy `Generator` that replays: one generator per name (order-independent, safe in loops), a new one per unnamed call (by call order), or from an explicit seed |
+| `resume.seed_for(name)` / `resume.seed` | stable `int` seed per name / the experiment seed |
+| `@resume.wrap` on a function | records a slow, side-effect-free function's return value per arguments |
+| `run.snapshot({...})` / `run.load_snapshot()` | optional: skip replaying the start of a very long run |
+
+Other behaviour: changed code is detected and reported (`on_divergence="stop"` to stop instead of
+continuing); a device change is detected (`on_backend_change="stop"`); `qpu_budget_s` stops cleanly before
+the job that would exceed it; global `random`/`numpy` and `qiskit_algorithms.algorithm_globals` are seeded.
+
+## Before spending QPU time
+
+```bash
+qresume selftest my_script.py -- my.qresume      # crash/resume at several points with synthetic results (no QPU)
+qresume check my_script.py --file my.qresume -- my.qresume   # can this file continue? (no IBM contact)
+qresume status my.qresume                        # calls, snapshots, device, QPU used, warnings
+```
+
+Other commands: `copy` (consistent copy while running), `export`, `quota`, `fork` (branch at a
+snapshot), `pack`/`unpack`, `compact`.
+
+## See it work
+
+[`examples/crash_and_resume.py`](https://github.com/set3523/Qiskit-resume/blob/master/examples/crash_and_resume.py) takes a plain Qiskit workload
+(VQE, QAOA, VQD from `qiskit_algorithms`, unmodified), wraps it, **kills the process part way**, runs it
+again and checks the result equals an uninterrupted run, logging every call to the console:
+
+```bash
+git clone https://github.com/set3523/Qiskit-resume && cd Qiskit-resume/examples
+pip install "qiskit-resume[examples]" scipy
+python crash_and_resume.py standard/qaoa_maxcut.py --kill-at-call 100 --compare
+```
+
+## Test results on real IBM hardware
+
+ibm_kingston, IBM Quantum Open Plan, 2026-10-24/25. Reproduce with
+[`examples/ibm/`](https://github.com/set3523/Qiskit-resume/tree/master/examples/ibm).
+
+| # | What was checked | Workload | Result |
+|---|---|---|---|
+| 1 | Estimator loop, hard kill, rerun: recorded calls replay from the file | VQE (EstimatorV2 + COBYLA) | PASS |
+| 2 | Rerun reconnects to the job submitted before the kill (still running / already finished), no resubmission | VQE, QAOA, checks 6, 9 | PASS |
+| 3 | QPU budget stops the run before the job that would exceed it | VQE | PASS |
+| 4 | Sampler loop, hard kill, reconnect, run to completion | QAOA Max-Cut (SamplerV2 + COBYLA) | PASS |
+| 5 | Jobs with several pubs and parameter sweeps replay bit-for-bit | Estimator 2 pubs (broadcast), Sampler 2 circuits (sweep) | PASS |
+| 6 | Kill right after submit, rerun reconnects to the same job id | Estimator | PASS |
+| 7 | Wait timeout stops cleanly, rerun reconnects to the waiting job | Estimator | PASS |
+| 8 | Device change (ibm_kingston -> ibm_fez) stops before any submission | Estimator | PASS |
+| 9 | New client-side `Estimator`/`Sampler` (qiskit-ibm-runtime >= 0.50): reconnect and replay | Estimator + Sampler | PASS |
+| - | IBM-side job failure and automatic retry | - | not seen yet (tested with a fake service) |
+| - | Real quota-exhausted stop | - | not seen yet (tested with a fake service) |
+| - | Reconnect while the job is still QUEUED | - | not seen yet (queue was empty; same code path as above) |
+
+Observed QPU cost per job on ibm_kingston: Sampler about 2 s, Estimator about 11-13 s (default error mitigation).
+
+## Limits
+
+- A single circuit execution cannot be paused (quantum states can't be saved); interruption
+  granularity is one primitive call.
+- Code that is not deterministic in ways qiskit-resume can't seed (time, external data) may
+  diverge on replay — you'll be told where.
+- Calls not made through Primitives (`backend.run`, direct `Statevector` maths) are not recorded.
+
+## Documentation
+
+[DECISIONS](https://github.com/set3523/Qiskit-resume/blob/master/docs/DECISIONS.md) (why) ·
+[ARCHITECTURE](https://github.com/set3523/Qiskit-resume/blob/master/docs/ARCHITECTURE.md) (layers and flow) ·
+[CONTRACTS](https://github.com/set3523/Qiskit-resume/blob/master/docs/CONTRACTS.md) (every module's inputs/outputs)
+
+License: MIT

qiskit_resume-0.2.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "qiskit-resume"
+dynamic = ["version"]
+description = "Record & replay layer that lets any Qiskit Primitives workflow resume after interruption without re-spending QPU time."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Jihoon" }]
+keywords = ["qiskit", "quantum", "checkpoint", "resume", "ibm-quantum", "vqe", "qaoa"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = [
+    "qiskit>=1.4",
+    "numpy>=1.23",
+]
+
+[project.urls]
+Homepage = "https://github.com/set3523/Qiskit-resume"
+Issues = "https://github.com/set3523/Qiskit-resume/issues"
+
+[project.optional-dependencies]
+ibm = ["qiskit-ibm-runtime>=0.30"]
+examples = ["qiskit-algorithms>=0.3"]
+dev = ["pytest>=7.0", "scipy"]
+
+[project.scripts]
+qresume = "qiskit_resume.tools.cli:main"
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.dynamic]
+version = { attr = "qiskit_resume._version.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["qiskit_resume*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-p no:cacheprovider"

qiskit_resume-0.2.0/qiskit_resume/__init__.py

@@ -0,0 +1,75 @@
+"""qiskit-resume: run a Qiskit Primitives script so it can be interrupted and resumed.
+
+Rerun the same script after any interruption: finished calls replay from a local .qresume file,
+an IBM job that was still running is reconnected (not resubmitted), only new work uses the QPU.
+
+How to add it to an existing script (also for AI assistants):
+
+    import qiskit_resume as resume
+
+    with resume.resume_run("my_run.qresume"):                   # 1. run everything inside this
+        backend = resume.backend()                              # 2. device: chosen once, reused on reruns
+        pm = resume.pass_manager(backend, optimization_level=1) # 3. instead of generate_preset_pass_manager
+        estimator = resume.wrap(EstimatorV2(mode=backend))     # 4. wrap every Estimator / Sampler
+        theta0 = resume.rng("init").uniform(-1, 1, n)           # 5. replace unseeded randomness
+        ...                                                     #    the rest of the script is unchanged
+
+    Rules
+    - Replace np.random.default_rng() (no seed), np.random.rand(), random.random() used for
+      algorithm inputs with draws from resume.rng("purpose"); a random int seed becomes
+      resume.seed_for("purpose"). resume.rng("x") returns the same generator for the same name,
+      so it is safe inside loops.
+    - Replace generate_preset_pass_manager(...) with resume.pass_manager(...) (same arguments);
+      it works anywhere a pass manager is accepted, e.g. QAOA(..., transpiler=pm).
+    - Do not create Estimators/Samplers inside library code you cannot wrap; pass wrapped ones in.
+    - Optional: @resume.wrap on a slow, deterministic classical function records its result so
+      reruns skip it (help(resume.wrap)).
+    - Verify before spending QPU time:  qresume selftest my_script.py -- <script args>
+      (crashes and resumes the script at several points with synthetic results; no QPU, no account).
+
+Full guide: https://github.com/set3523/Qiskit-resume (README "Add it to your script", llms.txt)
+"""
+
+from typing import Any
+
+from qiskit_resume._version import __version__
+from qiskit_resume.l0_disk.codec import EncodeError
+from qiskit_resume.l0_disk.db import AlreadyRunningError, IntegrityError
+from qiskit_resume.l1_record.runs import ImmutableSettingError
+from qiskit_resume.l4_api.primitive import BudgetExceeded, JobWaitTimeout, QuotaExhausted
+from qiskit_resume.l4_api.device import backend
+from qiskit_resume.l4_api.passmanager import pass_manager
+from qiskit_resume.l4_api.rng import NoActiveRunError, rng, seed_for
+from qiskit_resume.l4_api.run import BackendChangedStop, DivergenceStop, ResumeRun, get_active_run, resume_run
+from qiskit_resume.l4_api.wrap import wrap
+
+__all__ = [
+    "AlreadyRunningError",
+    "BackendChangedStop",
+    "BudgetExceeded",
+    "DivergenceStop",
+    "EncodeError",
+    "ImmutableSettingError",
+    "IntegrityError",
+    "JobWaitTimeout",
+    "NoActiveRunError",
+    "QuotaExhausted",
+    "ResumeRun",
+    "__version__",
+    "backend",
+    "get_active_run",
+    "pass_manager",
+    "resume_run",
+    "rng",
+    "seed",
+    "seed_for",
+    "wrap",
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "seed":  # resume.seed -> the active experiment's seed
+        from qiskit_resume.l4_api.rng import seed as _seed
+
+        return _seed()
+    raise AttributeError(f"module 'qiskit_resume' has no attribute {name!r}")

qiskit_resume-0.2.0/qiskit_resume/__main__.py

@@ -0,0 +1,3 @@
+from qiskit_resume.tools.cli import main
+
+raise SystemExit(main())

qiskit_resume-0.2.0/qiskit_resume/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

qiskit_resume-0.2.0/qiskit_resume/l0_disk/__init__.py

@@ -0,0 +1,5 @@
+"""L0 disk: the .qresume file, the blob store and the value codec.
+
+Knows nothing about Qiskit or what records mean.
+Depends on: standard library + numpy only. Contracts: docs/CONTRACTS.md section 1.
+"""

qiskit_resume-0.2.0/qiskit_resume/l0_disk/blobs/__init__.py

@@ -0,0 +1,13 @@
+"""l0_disk.blobs: content-addressed blob store (D-013 dedup).
+
+IN : bytes, kind
+OUT: BlobRef (str, SHA-256 hex); get(BlobRef) -> bytes; has(BlobRef) -> bool
+     content_hash(bytes) -> str
+Depends on: l0_disk.db
+Owns table: blobs
+Contract (signatures, types, errors, invariants): docs/CONTRACTS.md section 1.2
+"""
+
+from qiskit_resume.l0_disk.blobs.core import BlobStore, content_hash
+
+__all__ = ["BlobStore", "content_hash"]

qiskit_resume-0.2.0/qiskit_resume/l0_disk/blobs/core.py

@@ -0,0 +1,50 @@
+"""Content-addressed blob store inside the experiment DB (D-013 dedup).
+
+Identical payloads (same circuit, same observable, ...) are stored once and
+referenced by their SHA-256 hex digest.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import sqlite3
+
+from qiskit_resume.l0_disk.db import ExperimentDB
+
+
+_DDL = """
+CREATE TABLE IF NOT EXISTS blobs (
+    hash TEXT PRIMARY KEY,
+    kind TEXT NOT NULL,
+    size INTEGER NOT NULL,
+    data BLOB NOT NULL
+);
+"""
+
+
+def content_hash(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+class BlobStore:
+    def __init__(self, db: ExperimentDB) -> None:
+        db.ensure_schema(_DDL)
+        self._conn = db.conn
+
+    def put(self, data: bytes, *, kind: str = "raw") -> str:
+        """Store ``data`` (if new) and return its hash. Caller owns the transaction."""
+        h = content_hash(data)
+        self._conn.execute(
+            "INSERT OR IGNORE INTO blobs(hash, kind, size, data) VALUES (?, ?, ?, ?)",
+            (h, kind, len(data), sqlite3.Binary(data)),
+        )
+        return h
+
+    def get(self, h: str) -> bytes:
+        row = self._conn.execute("SELECT data FROM blobs WHERE hash = ?", (h,)).fetchone()
+        if row is None:
+            raise KeyError(f"blob not found: {h}")
+        return bytes(row[0])
+
+    def has(self, h: str) -> bool:
+        return self._conn.execute("SELECT 1 FROM blobs WHERE hash = ?", (h,)).fetchone() is not None

qiskit_resume-0.2.0/qiskit_resume/l0_disk/codec/__init__.py

@@ -0,0 +1,20 @@
+"""l0_disk.codec: value <-> bytes (D-013).
+
+IN : Python value (None/bool/int/float/complex/str/bytes/list/tuple/dict[str, ...]/numpy)
+OUT: bytes; decode(bytes) -> value
+     canonical_floats(array) -> bytes  12-significant-digit text used as hash input (shared by l1 and l3)
+Errors: EncodeError (with the path of the unstorable value, raised at record time)
+Option: allow_pickle=True (fragile across library versions)
+Depends on: nothing
+Contract (signatures, types, errors, invariants): docs/CONTRACTS.md section 1.3
+"""
+
+from qiskit_resume.l0_disk.codec.core import (
+    EncodeError,
+    canonical_floats,
+    canonical_scalar,
+    decode,
+    encode,
+)
+
+__all__ = ["EncodeError", "canonical_floats", "canonical_scalar", "decode", "encode"]