Metadata-Version: 2.5
Name: quqy
Version: 0.0.1
Summary: Honest error bars for quantum computations: shot-noise uncertainty for any circuit
Author: Melvina Quartey
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: confidence intervals,qiskit,quantum computing,shot noise,uncertainty quantification
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Provides-Extra: qiskit
Requires-Dist: qiskit>=2.0; extra == 'qiskit'
Provides-Extra: test
Requires-Dist: pytest>=7; extra == 'test'
Requires-Dist: qiskit>=2.0; extra == 'test'
Description-Content-Type: text/markdown

# quqy

Honest error bars for quantum computations.

Every number a quantum computer gives you is an average over a finite number of shots, so it carries an
error bar. `quqy` tells you how many shots you need before you run, and afterwards gives each result with
its standard error and a confidence interval that stays honest near ±1 and near 0 or 1. Those are the
places where the usual "value ± 1.96 × std" interval breaks.

**Version 0.0.1 accounts for shot noise only.** Device noise, error-mitigation and noise-model uncertainty
are planned for later versions. Every result says what its interval includes.

## Install

```
pip install quqy             # counts-based tools (numpy, scipy)
pip install "quqy[qiskit]"   # plus running circuits through Qiskit samplers
```

## Use

```python
from qiskit import QuantumCircuit
from qiskit.primitives import StatevectorSampler
import quqy

# Before running: shots for a target error
quqy.shots_needed(std=0.01)                     # standard error 0.01 on a Pauli → 10000
quqy.shots_needed(halfwidth=0.01)               # 95% interval of ±0.01 → 38415
quqy.shots_needed(relative=0.02, expected=0.4)  # 2% of a value near 0.4 → 50420

# Any circuit, any Pauli observables, any Qiskit sampler
qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)
est = quqy.estimate(qc, ["ZZ", "XX", "ZI"], StatevectorSampler(seed=1), shots=4000)
print(est)

# Probabilities from a measured circuit, keeping only shots where bit 3 reads 0
# p = quqy.probabilities(circuit, sampler, shots=100_000, bits=[0, 1, 2], postselect={3: 0})

# Counts you already have
quqy.from_counts({"00": 480, "11": 520}, observables=["ZZ", "ZI"])

# Are the error bars honest? Repeated runs against a known answer
runs = [quqy.estimate(qc, "ZI", StatevectorSampler(seed=s), shots=500) for s in range(200)]
quqy.coverage(runs, truth=0.0)      # fraction of intervals containing 0, with an uncertainty band
```

On IBM hardware, use `sampler=qiskit_ibm_runtime.SamplerV2(mode=backend)` and
`pass_manager=generate_preset_pass_manager(backend=backend, optimization_level=1)`.

## What the numbers mean

| Field | Meaning |
|---|---|
| `value` | The estimate: an expectation value or a probability |
| `std_error` | Its standard error. For one Pauli, √((1 − v²)/N), the same formula as Qiskit's `BackendEstimatorV2` |
| `lower`, `upper` | The confidence interval at `level` (default 0.95: in the long run, 95% of such intervals contain the true value) |
| `method` | `jeffreys` (default) or `wald` (value ± z·std). Weighted Pauli sums use `wald` with their exact variance |
| `shots`, `kept` | Shots run, and shots surviving post-selection |

**Why Jeffreys by default.** If all 4,000 shots of ⟨ZZ⟩ give +1, the standard error is 0 and the Wald
interval has zero width. Yet 4,000 shots cannot rule out a true value of 0.999. The Jeffreys interval comes
from the binomial distribution itself and keeps close to its stated coverage near the edges. See L. D. Brown,
T. T. Cai and A. DasGupta, *Statistical Science* 16, 101–133 (2001).

## License

Apache-2.0.
