uniqc.algorithmics.measurement.basis_rotation module#

Basis-rotation measurement for arbitrary single-qubit measurement bases.

uniqc.algorithmics.measurement.basis_rotation.basis_rotation_measurement(circuit, qubits=None, basis=None, shots=None)[source]#

Measure a circuit by applying basis-rotation gates and then measuring in the computational (Z) basis.

For each qubit, the rotation applied before measurement is determined by the corresponding entry in basis:

  • "Z" — no rotation (Z basis, default)

  • "X" — Hadamard gate (H), measures X basis

  • "Y" — S^dagger H, measures Y basis

  • "I" — no rotation (Z basis, identity)

When shots is None, the statevector simulator is used to return the exact probability distribution. When shots is given, the distribution is estimated from that many samples.

Parameters:

  • circuit (Circuit) – Quantum circuit (must contain MEASURE instructions).

  • qubits (List[int] | None) – Indices of qubits to include. None means all qubits.

  • basis (str | List[str] | None) – Per-qubit measurement basis. Accepts a single string such as "XYZ" (applied left-to-right to qubits, with each character one of "I" / "X" / "Y" / "Z"), a list of strings such as ["X", "Y", "Z"], or None (default, Z basis for all qubits).

  • shots (int | None) – Number of measurement shots. None returns the exact probability vector from the statevector simulator.

Returns:

When shots is None, a dict mapping each computational-basis outcome string (e.g. "01") to its probability. When shots is given, a dict mapping outcome strings to integer counts (frequency).

Raises:

  • ValueError – len(basis) does not match len(qubits).

  • ValueError – shots is not a positive integer.

  • ValueError – basis contains invalid characters.

Return type:

Dict[str, float] | List[float]

Example

>>> from uniqc.circuit_builder import Circuit
>>> from uniqc.algorithmics.measurement import basis_rotation_measurement
>>> c = Circuit()
>>> c.h(0)           # |0⟩ → (|0⟩+|1⟩)/√2
>>> c.cx(0, 1)       # Bell state (|00⟩+|11⟩)/√2
>>> c.measure(0, 1)
>>> # Measure qubit 0 in X basis, qubit 1 in Z basis
>>> probs = basis_rotation_measurement(c, basis="XZ")
>>> abs(probs["00"] - 0.5) < 1e-6   # P(0) in X basis for |+⟩ is 0.5
True