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:

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:

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:

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)

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:

What you get, honestly

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