Metadata-Version: 2.4
Name: qtwist
Version: 5.0.0
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: qiskit-aer>=0.14
Requires-Dist: qiskit-ibm-runtime>=0.40
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
Provides-Extra: torch
Requires-Dist: torch>=2.0; extra == "torch"
Provides-Extra: billing
Requires-Dist: razorpay>=2.0; extra == "billing"
Provides-Extra: full
Requires-Dist: torch>=2.0; extra == "full"
Requires-Dist: razorpay>=2.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 v5.0 (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.

It ships in two 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 instance** unlocked by a premium token.
  Costs are previewed *before* every run (IBM-style credit wallet). Adds the
  **QPU-Readiness Oracle**: a plain-English verdict on whether your circuit is
  good to submit to a real QPU.

> Live QPU routing is **roadmap**, not shipped. Everything today is classical
> simulation + an honest readiness verdict. See `qpu_backend.py` for the scaffold.

## Install

```
python -m pip install qtwist
```

(Optional full-stack extras for Qiskit circuit input and the adaptive-MPS
engine: `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
```

For small circuits (n ≤ 18) on the laptop you can also sample counts:

```python
counts = res.get_counts(shots=1024)             # Qiskit bit-order (LSB-first)
```

## 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 |

```python
print(res.explain())
# [QPU-Readiness: READY_FOR_QPU]
# Circuit is within Q-TWIST's validated envelope.  The simulated value ...
#   value=+0.993923  L1 bound=0.1287  cert=UNCERTIFIED (no live QPU validation)
```

## Quickstart — premium cloud tier (metered)

```python
from qtwist.aer_compat import QtwistSimulator
from qtwist.pricing import Wallet

wallet = Wallet(token="PRO_TOKEN")              # $99 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.96) ...

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 | metered credit wallet (~1 credit ≈ 1 GPU-min, $99/100) | instant | yes (cloud) |
| ENTERPRISE | on-prem / custom | quote-based | instant | roadmap |

## What you get, honestly

| Regime | What it means | What you get |
|---|---|---|
| CERTIFIED | within envelope, error budget below target, **validated against a live QPU ground truth** | certified expectation + 9-term budget (requires a real `qpu_backend`) |
| UNCERTIFIED | simulated and consistency-checked, but no QPU was available to validate | honest value + budget, marked UNCERTIFIED |
| REJECTED | no engine envelope can simulate this circuit | `RejectionResult` with reason + reformulation suggestions, zero compute spent |

We never market "Certified" without a live QPU behind it, and we never claim
live QPU integration that isn't shipped.

## 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 prelaunch_audit.py          # 61/61 correctness + honesty checks
python poc_scientist_programs.py   # 10 real scientist programs
python poc_research_suite.py       # 1024-qubit QEC via Engine C
python user_acceptance_test.py     # 20-qubit TFIM sweep + 100-qubit rejection
python realworld_test.py           # ordinary Qiskit programs vs exact reference
```
