uniqc.algorithms.core.measurement.pauli_expectation module

Pauli string expectation value measurement via basis rotation.

class uniqc.algorithms.core.measurement.pauli_expectation.PauliExpectation(circuit, pauli_string, shots=None)

Bases: object

Class-based interface for Pauli-string expectation measurement.

Convention: the constructor accepts a clean state-preparation Circuit (no measurement instructions). The class adds basis rotations and measurements internally; the input circuit is not mutated.

Example:

from uniqc.circuit_builder import Circuit
from uniqc.algorithms.core.measurement import PauliExpectation

c = Circuit()
c.h(0); c.cx(0, 1)
meas = PauliExpectation(c, "ZZ", shots=10000)
readouts = meas.get_readout_circuits()    # list[Circuit]
value = meas.execute("statevector")        # float in [-1, 1]

Parameters:

• circuit (Circuit)

• pauli_string (str | list[tuple])

• shots (int | None)

execute(backend='statevector', *, program_type='qasm', **kwargs)

Execute the readout circuits and return the expectation value.

Parameters:

• backend (str | object) – Either a backend-type name (string, e.g. "statevector") or a pre-built simulator object exposing simulate_statevector / simulate_shots.

• program_type (str) – Currently only "qasm" is supported.

• **kwargs – Forwarded to simulator construction when backend is a string.

Return type:

float

get_readout_circuits()

Return the list of readout circuits (one per measurement basis).

For a single Pauli string this returns a one-element list containing the basis-rotated, measured circuit.

Return type:

list[Circuit]

uniqc.algorithms.core.measurement.pauli_expectation.pauli_expectation(circuit, pauli_string, shots=None)

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

For each qubit i, the measurement basis is determined by the operator assigned to that qubit:

• '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 Simulator and end with measurement instructions.

• pauli_string (str | list[tuple]) –

  Pauli string in any of three accepted forms (case- insensitive):

  • Compact (length == n_qubits): "XYZ", "IZI".

  • Indexed ("Z0Z1"): operator-index pairs; any qubit not listed is identity. Matches the convention of uniqc.algorithms.core.ansatz.qaoa_ansatz.cost_hamiltonian().

  • Tuple list: [("Z", 0), ("Z", 1)] — same semantics as the indexed form.

• 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 is malformed, contains invalid characters, or its length / qubit indices do not fit the circuit.

• ValueError – shots is not a positive integer.

Return type:

float

Example

>>> from uniqc.circuit_builder import Circuit
>>> from uniqc.algorithms.core.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")               # compact form
1.0
>>> pauli_expectation(c, "Z0Z1")             # indexed form
1.0
>>> pauli_expectation(c, [("Z", 0), ("Z", 1)])  # tuple-list form
1.0

uniqc.algorithms.core.measurement.pauli_expectation.pauli_expectation_example()

Tiny PauliExpectation demo that returns ⟨ZZ⟩ on a Bell state (≈ 1.0).

Return type:

float