uniqc.algorithmics.measurement.pauli_expectation module#

Pauli string expectation value measurement via basis rotation.

uniqc.algorithmics.measurement.pauli_expectation.pauli_expectation(circuit, pauli_string, shots=None)[source]#

Measure the expectation value of a Pauli string on a circuit.

For each qubit i, the measurement basis is determined by pauli_string[i]:

  • 'I': trace out (identity, contributes trivially)

  • 'Z': measure in the computational (Z) basis — no rotation needed

  • 'X': apply Hadamard before Z measurement

  • 'Y': apply Sdag then Hadamard before Z measurement

When shots is None, the statevector simulator is used to compute the exact expectation analytically. When shots is given, the circuit is simulated shots times and the empirical frequency is used.

Parameters:

  • circuit (Circuit) – Quantum circuit. Must contain only gates supported by QASM_Simulator and end with measurement instructions.

  • pauli_string (str) – Case-insensitive Pauli string (e.g. "XYZ", "IZI"). Characters must be I, X, Y, or Z.

  • shots (int | None) – Number of measurement shots. None uses statevector mode for the exact analytical value.

Returns:

Expectation value ⟨psi|P|psi⟩ as a float in the interval [-1, 1].

Raises:

  • ValueError – pauli_string contains invalid characters or its length does not match the number of qubits in circuit.

  • ValueError – shots is not a positive integer.

Return type:

float

Example

>>> from uniqc.circuit_builder import Circuit
>>> from uniqc.algorithmics.measurement import pauli_expectation
>>> c = Circuit()
>>> c.h(0)
>>> c.cx(0, 1)          # Bell state (|00⟩+|11⟩)/√2
>>> c.measure(0, 1)
>>> pauli_expectation(c, "ZZ", shots=None)   # exact: 1.0
1.0
>>> abs(pauli_expectation(c, "ZZ", shots=10000) - 1.0) < 0.1
True