Metadata-Version: 2.4
Name: qtwist
Version: 7.0.0
Summary: Q-TWIST v7: certified-methodology quantum emulation SDK -- every number ships with its typed error bound and a machine-checkable certificate, or the request is refused. (Supersedes the 5.x legacy line.)
Author: Q-TWIST
License: Proprietary
Keywords: quantum,simulation,certified,error-budget,digital-twin,benchmarking
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Dynamic: license-file

# qtwist 7.0.0

Certified-methodology quantum emulation SDK: **every number ships with
its typed error bound and a machine-checkable certificate — or the
request is refused in milliseconds with a reasoned argument.**
Supersedes the 5.x legacy line (clean major break, same import name).

## Quickstart

    pip install qtwist==7.0.0

```python
from qtwist import QTWIST, Circuit, Observable

sdk = QTWIST()                       # mock Heron twin (default)
c = Circuit(3)
c.h(0); c.cx(0, 1); c.cx(1, 2)       # 3-qubit GHZ

out = sdk.query(c, Observable.zz(0, 2), eps_target=0.05)
print(out.result)                    # value +- typed bound [CERTIFIED]
print(sdk.verify(out.result.certificate, program=c))   # True
```

Expected: `value +0.910750`, `bound 0.024500 [CERTIFIED]`, and
standalone certificate verification returning `True`.

## How to read a result (two independent axes)

```
value       : +0.910750
bound       : 0.024500 [CERTIFIED]   <- eps-grade axis: the interval
                                      value +- bound is certified by
                                      typed bound arithmetic, GIVEN
                                      the twin's noise model
status      : Uncertified [Mock Calibration]   <- twin-trust axis:
                                      the default backend is a mock,
                                      so nothing is claimed about any
                                      real device
```

Tight bound on a mock twin is honest about being a mock; a loose bound
on a measured twin is honest about model uncertainty. Neither axis
borrows credibility from the other.

## Core calls

| Call | Returns |
|---|---|
| `sdk.query(program, observable, eps_target=..., seed=...)` | `QueryOutcome`: `.result` (value + bound + certificate) or `.rejection` (reason + suggestions + diagnostics) |
| `sdk.predict(circuit, observable, accuracy="max", ...)` | v5-compatible surface; `accuracy="max"` routes to the accuracy-first fleet |
| `sdk.get_counts(circuit, shots=2048)` | sampled counts + certified per-outcome halfwidth |
| `sdk.verify(certificate, program=...)` | standalone re-check: schema, budget-sum rule, type lattice, union bound, signature — no rerun |

Rejections are results, not exceptions: ask for a tolerance below the
calibration floor and you get `INFEASIBLE_TARGET` in ~7 ms with the
full term decomposition (eps_model, eps_drift, eps_readout_xtalk, ...)
and actionable suggestions. Q-TWIST never returns a wrong value in
place of a failure.

## Registering a measured calibration

The default twin is a mock. To run against your own measured
calibration:

```python
from qtwist import (QTWIST, CalibrationLake, CalibrationRecord)

lake = CalibrationLake()
lake.add(CalibrationRecord(key="readout.e0e1",
                           values=(0.008, 0.016), ci=(0.002, 0.002),
                           source="experiment:my-lab",
                           method="confusion-matrix",
                           timestamp="2026-09-05 00:00:00+00:00"))
snap = lake.snapshot(device="my-device-v1",   # non-fake name
                     drift_per_hour=0.001, staleness_hours=1.5)
sdk = QTWIST(snapshot=snap)      # status now: Certified [OK]
```

Every record carries values + CIs + source + method + timestamp:
provenance is part of the type system. A live SPRT drift monitor
(`sdk.observe(...)`, `sdk.twin_status`) rides on top.

## What's inside

- 8 engines behind one certified oracle: quantum trajectories (A),
  exact density-matrix (B), Pauli-DAOE (C), adaptive MPS (D),
  TDVP accuracy-first (H), CHIMERA geometry synthesis (X),
  analog/DAQC (Q), logical FTQC twin (L).
- Twelve-term typed epsilon budget; default confidence 1e-3 delta;
  composition theorem for stacked queries.
- Signed Emulation Certificates (`qtwist.cert.v1`), standalone
  verifiable without re-running the simulation.
- Circuit API: `h x y z s sdg t rx ry rz sx u3 cx cz swap iswap rxx
  ryy rzz rzx ccx`; observables `z`, `zz`, Pauli sums.
- Requires Python >= 3.10 and numpy. Nothing else.

## Status (honest)

This is an **existence release**: the SDK is parked here to hold the
name and the version line. It is complete and audited (adversarial
audit 73/73; hardening lineage 80/80; 43-check robustness battery;
23/23 probe suite; 9,480-line certified core, hash-pinned; release
commit `77b562c`, v7.0.0), but it ships **mock device calibration
only** (`fake-heron`) — no real-QPU backends in the wheel. Real-device
validation evidence lives in the external ARENA ledger: two
IBM-marrakesh campaigns are on record (layout-pinned; campaign #0002
coverage 6/6 by interval overlap at ±0.05, 4/6 under the stricter
point-containment reading with two near-misses — erratum E1 on
record); the current arena certificate is **PROVISIONAL** pending the
drift-poll and depth-ladder upgrade now in progress. Certificates use
demo-grade HMAC signatures; production Ed25519 signing is the 7.1
roadmap.

If you found this package before the announcement: it is real,
tested, and safe to try — it is simply not the launch.

## Lineage

5.x (2026-08) was the pre-hardening product line with a web console;
it remains on PyPI as the legacy museum piece. 7.0.0 is the
certified-instrument line: different contract, numpy-only, one
public name.
