qtwist 0.1.0b0__tar.gz

qtwist-0.1.0b0/LICENSE

@@ -0,0 +1,15 @@
+Q-TWIST — PROPRIETARY SOFTWARE
+
+Copyright (c) 2026 Q-TWIST. All rights reserved.
+
+This software is the proprietary property of Q-TWIST. It is licensed for
+use only under the terms of a separate written license agreement with
+Q-TWIST. No rights are granted except as expressly set forth in such an
+agreement. Unauthorized reproduction, distribution, or use is prohibited.
+
+The Q-TWIST Python SDK (`pip install qtwist`) and web console are 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 non-infringement.
+
+For licensing inquiries, contact Q-TWIST.

qtwist-0.1.0b0/MANIFEST.in

@@ -0,0 +1,15 @@
+include pyproject.toml
+include README.md
+include LICENSE
+
+recursive-include qtwist *.py
+recursive-include qtwist/web *.py *.html *.css *.js
+recursive-include qtwist_core *.py *.pt *.json py.typed
+recursive-include tests *.py
+
+prune build
+prune dist
+prune .venv
+prune research
+
+global-exclude *.pyc __pycache__

qtwist-0.1.0b0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: qtwist
+Version: 0.1.0b0
+Summary: Q-TWIST: certified-methodology digital twin for noisy quantum processors - engines, Python SDK, and web console.
+Author: Q-TWIST
+License: Proprietary
+Project-URL: Homepage, https://qtwist.example
+Keywords: quantum,simulation,certified,digital-twin,noise
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.0
+Requires-Dist: scipy>=1.11
+Requires-Dist: threadpoolctl>=3.0
+Requires-Dist: qiskit>=1.0
+Requires-Dist: quimb>=1.8
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn[standard]>=0.27
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: razorpay>=2.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: websockets>=12.0
+Provides-Extra: torch
+Requires-Dist: torch>=2.0; extra == "torch"
+Provides-Extra: qpu
+Requires-Dist: qiskit-aer>=0.14; extra == "qpu"
+Requires-Dist: qiskit-ibm-runtime>=0.40; extra == "qpu"
+Provides-Extra: jupyter
+Requires-Dist: jupyter-server>=2.0; extra == "jupyter"
+Requires-Dist: notebook>=7.0; extra == "jupyter"
+Provides-Extra: full
+Requires-Dist: torch>=2.0; extra == "full"
+Requires-Dist: razorpay>=2.0; extra == "full"
+Requires-Dist: qiskit-aer>=0.14; extra == "full"
+Requires-Dist: qiskit-ibm-runtime>=0.40; extra == "full"
+Requires-Dist: jupyter-server>=2.0; extra == "full"
+Requires-Dist: notebook>=7.0; extra == "full"
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: httpx>=0.27; extra == "test"
+Dynamic: license-file
+
+# Q-TWIST (Beta) — The Honest Oracle
+
+Q-TWIST is a physics-constrained quantum-circuit inference engine that tells
+you **what it can simulate, to what error, and whether your circuit is worth
+running on real hardware** — and refuses, honestly, when it cannot. No silent
+wrong numbers. No "certified digital twin" marketing. Rigorous L1 error bounds,
+and an explicit refusal with a fix when a circuit is out of envelope.
+
+> **Status / version.** PyPI `0.1.0b0` is the current **beta** preview. A prior
+> stable `5.0.0` is deprecated; install the beta with
+> `pip install qtwist==0.1.0b0` (or `pip install --pre qtwist`).
+
+It ships in three tiers:
+
+* **FREE** — a local **`AerSimulator`-style drop-in** that runs on your laptop
+  CPU. Drop it into any Qiskit expectation-value workflow. No token, no bill.
+* **PRO** — a **metered cloud GPU worker** unlocked by an API key / premium
+  token. Costs are previewed *before* every run (a metered credit wallet).
+* **ENTERPRISE** — a **warm GPU worker pool** (low-latency 1024-qubit runs) plus
+  custom deployment and SLAs.
+
+Everything today is classical simulation + an honest readiness verdict. The
+"certified" label is only ever applied when a live QPU ground truth is behind it;
+otherwise results are marked `UNCERTIFIED`.
+
+## Install
+
+```
+python -m pip install qtwist==0.1.0b0
+```
+
+Optional full-stack extras (Qiskit Aer input, the adaptive-MPS engine, and the
+in-browser notebook): `python -m pip install -e ".[full]"`.
+
+## Quickstart — free local drop-in
+
+You only need standard Qiskit. `QtwistSimulator` mirrors `AerSimulator`'s
+`run()` / `result()` surface for the expectation-value workflow:
+
+```python
+from qiskit import QuantumCircuit
+from qtwist.aer_compat import QtwistSimulator
+
+# 20-qubit transverse-field Ising model, 3 layers
+qc = QuantumCircuit(20)
+for _ in range(3):
+    for i in range(19):
+        qc.rzz(0.5, i, i + 1)
+    for i in range(20):
+        qc.rx(0.3, i)
+
+sim = QtwistSimulator(instance="local")          # free, laptop CPU
+res = sim.run(qc, observable="Z0Z1", epsilon_target=0.05).result()
+
+print(f"<Z0 Z1> = {res.value():+.6f}  +/-  {res.error:.4f}")
+print(res.explain())                            # QPU-Readiness Oracle verdict
+```
+
+## The QPU-Readiness Oracle
+
+Every result carries a `qpu_readiness` verdict — the one thing you want to
+know before spending real QPU queue time:
+
+| Verdict | Meaning | What to do |
+|---|---|---|
+| `READY_FOR_QPU` | Within Q-TWIST's validated envelope; value trustworthy within the reported L1 bound | Run it on hardware to validate the physics |
+| `NEEDS_FIXES` | Rejected only for a fixable issue (long-range gate, multi-controlled gate, wrong topology) | Apply the listed suggestions, re-run |
+| `INTRACTABLE` | Beyond classical simulation / QPU-advantage territory | Run on hardware directly if you must; Q-TWIST can't pre-validate |
+
+## Quickstart — premium cloud tier (metered)
+
+```python
+from qtwist.aer_compat import QtwistSimulator
+from qtwist.pricing import Wallet
+
+wallet = Wallet(token="PRO_TOKEN")              # $50 base = 100 credits
+sim = QtwistSimulator(instance="cloud:PRO_TOKEN", wallet=wallet, topology="1D_chain")
+
+print(sim.estimate(qc))                          # pre-flight cost, never bills
+# [PRO / cloud] engine=ENGINE_D n=20 depth=39 -- est. 0.97 credits (~$0.49) ...
+
+res = sim.run(qc, observable="Z0Z1").result()    # charged only after confirm
+print(res.explain())
+```
+
+Tiers:
+| Tier | Runs on | Billing | Capability Classifier | QPU-Readiness Oracle |
+|---|---|---|---|---|
+| FREE | laptop CPU | free | instant | yes (local) |
+| PRO | cloud GPU worker | metered credit wallet (~1 credit ≈ 1 GPU-min, $50/100) | instant | yes (cloud) |
+| ENTERPRISE | warm GPU worker pool / custom | $500 base, quote for scale | instant | yes (cloud) |
+
+## Web console & 1024-qubit GPU tier
+
+For paid 1024-qubit (Engine-D MPS) execution, Q-TWIST runs as a small web
+console plus a **warm GPU worker pool**:
+
+* The console (cheap, always-on, CPU) serves the UI, auth, billing, and the
+  interactive playground. **Free** callers run in-process on CPU; **paid**
+  (Pro/Enterprise) callers are delegated to the GPU worker pool.
+* `SimDispatcher` (`qtwist/web/dispatch.py`) routes free → local CPU and paid →
+  an `HttpWorker` that calls the worker's internal `/api/worker/predict`.
+* Each worker is the same app image with `QTWIST_GPU=1` (cupy MPS path), kept
+  warm by `scripts/gpu_pool.py` (Local for dev, JarvisLabs SDK for prod).
+
+Launch locally:
+
+```
+qtwist serve                      # or: uvicorn qtwist.web.app:app --port 8000
+```
+
+Or deploy the full stack with Docker Compose (console + GPU worker + redis):
+
+```
+QTWIST_WORKER_TOKEN=$(openssl rand -hex 24) docker compose up --build
+```
+
+See `DEPLOY.md` for the Render / Docker / JarvisLabs GPU-pool walkthrough.
+
+## What "1024 qubits" really means (honesty note)
+
+Q-TWIST can run **1024-qubit** circuits, but only inside the **Engine-D (adaptive
+MPS) envelope**: a **local** observable (≤ 30 qubits), a **1D chain**,
+**nearest-neighbour** gates, and **area-law** entanglement. Inside that envelope
+it is exact and fast (e.g. GHZ-1024 `<Z0Z1> = +1.0000`). It is **not universal**:
+long-range gates, global observables > 30 qubits, QFT, dynamic circuits, and
+multi-controlled gates are **rejected** with a reason and a fix — never faked.
+
+## Topology support
+
+`QTWISTBackend(topology=...)` and `predict(..., topology=...)` accept:
+
+* `"1D_chain"` — Engine D (adaptive MPS) envelope, up to 1024 qubits
+* `"2D_heavy_hex"` — shallow circuits via Engine C; deep heavy-hex is rejected with routing guidance
+* `"all_to_all"` — fully connected, any engine that fits
+* a Qiskit `CouplingMap` — edges are read from the map (1D chains are detected automatically)
+
+## Verification
+
+```
+python -m pytest tests/                       # dispatch + engine honesty tests
+python research/demo_1024.py                  # 1024-qubit capability demo (GHZ exact)
+```

qtwist-0.1.0b0/README.md

@@ -0,0 +1,143 @@
+# Q-TWIST (Beta) — The Honest Oracle
+
+Q-TWIST is a physics-constrained quantum-circuit inference engine that tells
+you **what it can simulate, to what error, and whether your circuit is worth
+running on real hardware** — and refuses, honestly, when it cannot. No silent
+wrong numbers. No "certified digital twin" marketing. Rigorous L1 error bounds,
+and an explicit refusal with a fix when a circuit is out of envelope.
+
+> **Status / version.** PyPI `0.1.0b0` is the current **beta** preview. A prior
+> stable `5.0.0` is deprecated; install the beta with
+> `pip install qtwist==0.1.0b0` (or `pip install --pre qtwist`).
+
+It ships in three tiers:
+
+* **FREE** — a local **`AerSimulator`-style drop-in** that runs on your laptop
+  CPU. Drop it into any Qiskit expectation-value workflow. No token, no bill.
+* **PRO** — a **metered cloud GPU worker** unlocked by an API key / premium
+  token. Costs are previewed *before* every run (a metered credit wallet).
+* **ENTERPRISE** — a **warm GPU worker pool** (low-latency 1024-qubit runs) plus
+  custom deployment and SLAs.
+
+Everything today is classical simulation + an honest readiness verdict. The
+"certified" label is only ever applied when a live QPU ground truth is behind it;
+otherwise results are marked `UNCERTIFIED`.
+
+## Install
+
+```
+python -m pip install qtwist==0.1.0b0
+```
+
+Optional full-stack extras (Qiskit Aer input, the adaptive-MPS engine, and the
+in-browser notebook): `python -m pip install -e ".[full]"`.
+
+## Quickstart — free local drop-in
+
+You only need standard Qiskit. `QtwistSimulator` mirrors `AerSimulator`'s
+`run()` / `result()` surface for the expectation-value workflow:
+
+```python
+from qiskit import QuantumCircuit
+from qtwist.aer_compat import QtwistSimulator
+
+# 20-qubit transverse-field Ising model, 3 layers
+qc = QuantumCircuit(20)
+for _ in range(3):
+    for i in range(19):
+        qc.rzz(0.5, i, i + 1)
+    for i in range(20):
+        qc.rx(0.3, i)
+
+sim = QtwistSimulator(instance="local")          # free, laptop CPU
+res = sim.run(qc, observable="Z0Z1", epsilon_target=0.05).result()
+
+print(f"<Z0 Z1> = {res.value():+.6f}  +/-  {res.error:.4f}")
+print(res.explain())                            # QPU-Readiness Oracle verdict
+```
+
+## The QPU-Readiness Oracle
+
+Every result carries a `qpu_readiness` verdict — the one thing you want to
+know before spending real QPU queue time:
+
+| Verdict | Meaning | What to do |
+|---|---|---|
+| `READY_FOR_QPU` | Within Q-TWIST's validated envelope; value trustworthy within the reported L1 bound | Run it on hardware to validate the physics |
+| `NEEDS_FIXES` | Rejected only for a fixable issue (long-range gate, multi-controlled gate, wrong topology) | Apply the listed suggestions, re-run |
+| `INTRACTABLE` | Beyond classical simulation / QPU-advantage territory | Run on hardware directly if you must; Q-TWIST can't pre-validate |
+
+## Quickstart — premium cloud tier (metered)
+
+```python
+from qtwist.aer_compat import QtwistSimulator
+from qtwist.pricing import Wallet
+
+wallet = Wallet(token="PRO_TOKEN")              # $50 base = 100 credits
+sim = QtwistSimulator(instance="cloud:PRO_TOKEN", wallet=wallet, topology="1D_chain")
+
+print(sim.estimate(qc))                          # pre-flight cost, never bills
+# [PRO / cloud] engine=ENGINE_D n=20 depth=39 -- est. 0.97 credits (~$0.49) ...
+
+res = sim.run(qc, observable="Z0Z1").result()    # charged only after confirm
+print(res.explain())
+```
+
+Tiers:
+| Tier | Runs on | Billing | Capability Classifier | QPU-Readiness Oracle |
+|---|---|---|---|---|
+| FREE | laptop CPU | free | instant | yes (local) |
+| PRO | cloud GPU worker | metered credit wallet (~1 credit ≈ 1 GPU-min, $50/100) | instant | yes (cloud) |
+| ENTERPRISE | warm GPU worker pool / custom | $500 base, quote for scale | instant | yes (cloud) |
+
+## Web console & 1024-qubit GPU tier
+
+For paid 1024-qubit (Engine-D MPS) execution, Q-TWIST runs as a small web
+console plus a **warm GPU worker pool**:
+
+* The console (cheap, always-on, CPU) serves the UI, auth, billing, and the
+  interactive playground. **Free** callers run in-process on CPU; **paid**
+  (Pro/Enterprise) callers are delegated to the GPU worker pool.
+* `SimDispatcher` (`qtwist/web/dispatch.py`) routes free → local CPU and paid →
+  an `HttpWorker` that calls the worker's internal `/api/worker/predict`.
+* Each worker is the same app image with `QTWIST_GPU=1` (cupy MPS path), kept
+  warm by `scripts/gpu_pool.py` (Local for dev, JarvisLabs SDK for prod).
+
+Launch locally:
+
+```
+qtwist serve                      # or: uvicorn qtwist.web.app:app --port 8000
+```
+
+Or deploy the full stack with Docker Compose (console + GPU worker + redis):
+
+```
+QTWIST_WORKER_TOKEN=$(openssl rand -hex 24) docker compose up --build
+```
+
+See `DEPLOY.md` for the Render / Docker / JarvisLabs GPU-pool walkthrough.
+
+## What "1024 qubits" really means (honesty note)
+
+Q-TWIST can run **1024-qubit** circuits, but only inside the **Engine-D (adaptive
+MPS) envelope**: a **local** observable (≤ 30 qubits), a **1D chain**,
+**nearest-neighbour** gates, and **area-law** entanglement. Inside that envelope
+it is exact and fast (e.g. GHZ-1024 `<Z0Z1> = +1.0000`). It is **not universal**:
+long-range gates, global observables > 30 qubits, QFT, dynamic circuits, and
+multi-controlled gates are **rejected** with a reason and a fix — never faked.
+
+## Topology support
+
+`QTWISTBackend(topology=...)` and `predict(..., topology=...)` accept:
+
+* `"1D_chain"` — Engine D (adaptive MPS) envelope, up to 1024 qubits
+* `"2D_heavy_hex"` — shallow circuits via Engine C; deep heavy-hex is rejected with routing guidance
+* `"all_to_all"` — fully connected, any engine that fits
+* a Qiskit `CouplingMap` — edges are read from the map (1D chains are detected automatically)
+
+## Verification
+
+```
+python -m pytest tests/                       # dispatch + engine honesty tests
+python research/demo_1024.py                  # 1024-qubit capability demo (GHZ exact)
+```

qtwist-0.1.0b0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qtwist"
+version = "0.1.0b0"
+description = "Q-TWIST: certified-methodology digital twin for noisy quantum processors - engines, Python SDK, and web console."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Proprietary" }
+authors = [{ name = "Q-TWIST" }]
+keywords = ["quantum", "simulation", "certified", "digital-twin", "noise"]
+dependencies = [
+    "numpy>=2.0",
+    "scipy>=1.11",
+    "threadpoolctl>=3.0",
+    "qiskit>=1.0",
+    "quimb>=1.8",
+    "fastapi>=0.110",
+    "uvicorn[standard]>=0.27",
+    "pydantic>=2.0",
+    "python-multipart>=0.0.9",
+    "razorpay>=2.0",
+    "httpx>=0.27",
+    "websockets>=12.0",
+]
+
+[project.optional-dependencies]
+torch = ["torch>=2.0"]
+# Heavy packages needed ONLY for the live-QPU / synthetic-twin noise path.
+# The web console and default engine predictions do NOT require these, so they
+# are opt-in to keep installs (and PaaS builds) light.
+qpu = ["qiskit-aer>=0.14", "qiskit-ibm-runtime>=0.40"]
+# In-browser Jupyter workspace (real notebook + terminal) embedded in the console.
+jupyter = ["jupyter-server>=2.0", "notebook>=7.0"]
+full = ["torch>=2.0", "razorpay>=2.0", "qiskit-aer>=0.14", "qiskit-ibm-runtime>=0.40", "jupyter-server>=2.0", "notebook>=7.0"]
+test = ["pytest>=8.0", "httpx>=0.27"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+filterwarnings = [
+    "ignore::DeprecationWarning",
+]
+
+[project.scripts]
+qtwist = "qtwist.cli:main"
+
+[project.urls]
+Homepage = "https://qtwist.example"
+
+[tool.setuptools.packages.find]
+include = ["qtwist*", "qtwist_core*"]
+
+[tool.setuptools.package-data]
+qtwist_core = ["certification/models/*.pt", "certification/models/*.json", "py.typed"]
+qtwist = ["web/static/*.html", "web/static/*.css", "web/static/*.js"]

qtwist-0.1.0b0/qtwist/__init__.py

@@ -0,0 +1,15 @@
+# Q-TWIST (beta) — Python SDK Package
+
+__version__ = "0.1.0b0"
+
+# Expose the engine packages (physics / router / core / certification) as
+# top-level importable modules via the qtwist_core path shim.
+import qtwist_core  # noqa: F401
+
+from qtwist.api import QTWISTBackend, PredictionResult, RejectionResult
+from qtwist.aer_compat import QtwistSimulator, QtwistJob, QtwistResult
+
+__all__ = [
+    "QtwistSimulator", "QtwistJob", "QtwistResult",
+    "QTWISTBackend", "PredictionResult", "RejectionResult",
+]

qtwist-0.1.0b0/qtwist/__main__.py

@@ -0,0 +1,5 @@
+"""Enable `python -m qtwist.cli` execution."""
+from qtwist.cli import main
+
+if __name__ == "__main__":
+    main()