Swap Test¶

Category C3 · Module oracq.algorithms.common.estimation · 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¶

swap_test(first, second)

API entry point: swap_test

first / second: preparations of two same-width states (SP), requiring zero input and a clean workspace (the checked_state_preparation contract, checked at generation time). Mismatched widths raise ValidationError.

Returns an 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 basis_state(1, 0) 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), and the module as a whole is at stage V2.

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 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
Two-bit state	2 bits each	all four	$F=0.125$, $P(0)=0.5625$, error $1.1\times10^{-16}$

Reproduction command:

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-).

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
Two-bit state	2 bits each	all four	\(F=0.125\), \(P(0)=0.5625\), error \(1.1\times10^{-16}\)