Hadamard Test

English · 简体中文

Category C3 · Module oracq.algorithms.common.estimation · Stage V2

Overview

Measures the real or imaginary part of the complex expectation value \(\langle\psi|U|\psi\rangle\): after a single probe bit interferes through the controlled \(U\), the Z expectation of probe equals the selected component. This operation performs no measurement; sampling and the classical computation of probability differences are done by the host.

Interface and input model

hadamard_test(unitary, preparation=None, *, component="real")

API entry point: hadamard_test

• unitary: a complete unitary Operation, or a block encoding with no signal bit and alpha=1 (UO, adapted via as_block_encoding); inputs with a signal bit or \(\alpha\ne 1\) raise ValidationError at generation time.

• preparation: the initial state preparation (SP, zero input + clean workspace); when omitted, the zero basis state of the target space is used (basis_state(width)).

• component: "real" or "imag".

Returns an Operation with registers target, work, and probe. Module attributes:

Attribute	Meaning
algorithm	"hadamard_test"
readout_register	"probe"
component	"real" / "imag"

The preparation width must equal the unitary width; an illegal component value raises an error at generation time.

Implementation notes

The circuit is preparation \(\to\) H(probe) \(\to\) controlled \(U\) \(\to\) (for the imaginary component, a \(-\pi/2\) phase applied to probe) \(\to\) H(probe). The imaginary readout places an \(S^\dagger\)-type phase after the controlled invocation, rotating the orthogonal component into the Z basis. The controlled invocation adapts to the BE interface with a zero-width signal view (b["work"][:0]), so BE-form inputs introduce no signal bit.

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: construction and attribute assertions in tests/core/test_algorithm_expansion.py:AlgorithmExpansionTests.

• Numerical: AlgorithmExpansionTests.test_hadamard_test_real_and_imaginary — a single-bit phase gate (angle 0.6, eigenvalue \(e^{0.6i}\)) acting on \(|1\rangle\); the real/imag components are cross-checked against \(p(0)-p(1)=\cos 0.6\) and \(\sin 0.6\) respectively, with 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.

Related links

• Source: src/oracq/algorithms/common/estimation.py

• API reference: Phase, amplitude, and overlap estimation

• Same-group pages: SWAP test (the corresponding readout for the overlap of two states)

• Validation matrix: Validation coverage matrix

Numerical validation

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

• A single-bit phase gate \(U=\mathrm{diag}(1,e^{i\theta})\) acting on \(|1\rangle\) (\(\theta=0.6\) and \(-1.1\)): the closed-form expectation is \(e^{i\theta}\).

• A two-bit diagonal unitary \(U|x\rangle=e^{i\theta_x}|x\rangle\) (angle table \((0.35,-0.9,1.7,0.55)\), implemented as a controlled global phase) paired with the gate_state_prep complex-amplitude preparation \(\psi=(0.5,\,0.5i,\,0.5,\,-0.5)\): the expectation value \(\sum_x|\psi_x|^2 e^{i\theta_x}\) is computed independently with the math library.

• Backend paths: reference, rir-pysparq, adapter-pysparq, and originir-ext; the Z expectation of probe, \(p(0)-p(1)\), is compared against the real/imaginary components of the expectation value.

Case	Scale	Path	Metric value
Phase gate \(\theta=0.6\)	1 target bit	all four	real \(=0.8253356\) (\(\cos\theta\)), imag \(=0.5646425\) (\(\sin\theta\)), error \(\le 5.6\times10^{-16}\)
Phase gate \(\theta=-1.1\)	1 target bit	all four	real \(=0.4535961\), imag \(=-0.8912074\), error \(\le 4.4\times10^{-16}\)
Diagonal unitary + complex preparation	2 target bits	all four	real \(=0.5711657\), imag \(=0.2684807\), error \(\le 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 hadamard-).