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)
```
