# Swap Test

**English** · <a href="../../zh/manual/algorithms/swap-test.html">简体中文</a>

> Category C3 · Module [`oracq.algorithms.common.estimation`](../../api/algorithms/common/estimation.rst) · Stage V2

## Overview

Measures the squared modulus of the overlap $F=|\langle a|c\rangle|^2$ of two pure states: the controlled swap interferes the two states' symmetric component onto the probe,

$$
P(\text{probe}=0) = \frac{1+F}{2}.
$$

This operation performs no measurement; sampling and statistics are done by the host.

## Interface and input model

```python
swap_test(first, second)
```

API entry point: {obj}`swap_test <oracq.algorithms.common.estimation.swap_test>`

- `first` / `second`: preparations of two same-width states (SP), requiring zero input and a clean workspace (the {obj}`checked_state_preparation <oracq.algorithms.input_model.interfaces.checked_state_preparation>` contract, checked at generation time). Mismatched widths raise {obj}`ValidationError <oracq.infrastructure.ir.ValidationError>`.

Returns an {obj}`Operation <oracq.infrastructure.builder.Operation>` with registers `left`, `right`, `left_work`, `right_work`, and `probe`. Module attributes:

| Attribute | Meaning |
|---|---|
| `algorithm` | `"swap_test"` |
| `readout_register` | `"probe"` |

## Implementation notes

The two preparations are only invoked forward; the conditional swap (`swap` under `control(probe)`) is generated by the algorithm. `left`/`right` each carry an independent work register, and workspace cleanliness is guaranteed by the SP contract — dirty preparations annotated `clean_work=False` are rejected at generation time. The readout decodes $F$ from the probe zero-probability via the formula above.

## Validation approach

Category C3 (acceptance criterion in `docs/development/validation-plan.md` §2: the output distribution equals the closed-form expectation). The three layers of evidence match the `estimation.py` row of `docs/development/validation-coverage.md`:

- Structure: `tests/core/test_algorithm_expansion.py:AlgorithmExpansionTests`, where `test_measurement_algorithms_require_clean_preparation` covers the dirty-preparation rejection path (`clean_work=False` raises `ValidationError`).
- Numerical: `AlgorithmExpansionTests.test_swap_test_overlap` — pairwise combinations of {obj}`basis_state(1, 0) <oracq.algorithms.input_model.oracles.basis_state>` and `basis_state(1, 1)`: $P(\text{probe}=0)=1$ for the same basis state ($F=1$) and $1/2$ for orthogonal basis states ($F=0$), places=10.
- Binding: the module row is recorded as "—".

The witness technique is exact state-vector simulation, taking the probe marginal distribution and cross-checking it against the closed form; no sampling assertions are made.

## Known gaps and planned stages

This algorithm has no gap of its own; the only gap registered for `estimation.py` belongs to the QAE confidence-interval claim (see [amplitude estimation](qae.md)), and the module as a whole is at stage V2.

## Related links

- Source: `src/oracq/algorithms/common/estimation.py`
- API reference: [Phase, amplitude, and overlap estimation](../../api/algorithms/common/estimation.rst)
- Same-group pages: [Hadamard test](hadamard-test.md) (the corresponding readout for the expectation of a single unitary)
- Validation matrix: [Validation coverage matrix](../../development/validation-coverage.md)

## Numerical validation

`tests/verification/verify_estimation.py` performs probability-level numerical validation of this interface on real backends (4 cases in total, all passing). Experimental design:

- Instances: pairs of pure states prepared by {obj}`gate_state_prep <oracq.algorithms.input_model.oracles.gate_state_prep>`, covering $F=1$ (same state), $F\approx 0$ (orthogonal), $F=0.36$ (partial overlap), and a two-bit state with $F=0.125$; the overlap $F=|\langle a|c\rangle|^2$ is computed independently by numpy from the input amplitude vectors.
- Backend paths: reference, rir-pysparq, adapter-pysparq, and originir-ext; $P(\text{probe}=0)$ is compared against $(1+F)/2$.

| Case | Scale | Path | Metric value |
|---|---|---|---|
| Same state $(0.6,0.8)$ | 1 bit each | all four | $F=1$, $P(0)=1$, error $2.2\times10^{-16}$ |
| Orthogonal $(0.6,0.8)$ vs $(0.8,-0.6)$ | 1 bit each | all four | $F\approx 0$, $P(0)=0.5$, error $1.1\times10^{-16}$ |
| Partial overlap $|0\rangle$ vs $(0.6,0.8)$ | 1 bit each | all four | $F=0.36$, $P(0)=0.68$, error $2.2\times10^{-16}$ |
| Two-bit state | 2 bits each | all four | $F=0.125$, $P(0)=0.5625$, error $1.1\times10^{-16}$ |

Reproduction command:

```bash
PYTHONPATH=src /home/agony/projects/qcfd-dev/quantum-cfd-software/.venv/bin/python tests/verification/verify_estimation.py
```

Artifact path: `out/verification/estimation.json` (case names prefixed `swap-test-`).