exp_vals

executor_expectation_values(bool_array, basis_dict, /, meas_basis_axis=None, *, avg_axis=None, measurement_flips=None, pauli_signs=None, postselect_mask=None, gamma_factor=None, rescale_factors=None)

Computes expectation values from boolean data and metadata, aiming for compatibility with the components of a result from Executor in qiskit_ibm_runtime .

Uses data in bool_array, acquired with measurement bases as ordered in keys of basis_dict, to compute observables encoded in values of basis_dict.

Optionally allows averaging over additional axes of bool_array, as when twirling.

Optionally supports measurement twirling, PEC, and postselection.

Parameters

• bool_array (ndarray[tuple[int, ...], dtype[bool]]) – Boolean array, presumably representing data from measured qubits. The last two axes are the number of shots and number of classical bits, respectively. The least significant bit is assumed to be at index 0 of the bits axis. If meas_basis_axis is given, that axis of bool_array indexes the measurement bases, with length len(basis_dict).
• basis_dict (dict[Pauli, list[SparsePauliOp | None]]) – This dict encodes how the data in bool_array should be used to estimate the desired list of Pauli observables. The ith key is a measurement basis assumed to correspond to the ith slice of bool_array along the meas_basis_axis axis. Each dict value is a list of length equal to the number of desired observables. The jth element of this list is a SparsePauliOp assumed to be compatible (qubit-wise commuting) with the measurement-basis key. In place of a SparsePauliOp, None may be used to represent the zero operator, when a basis is not used to compute an observable. The jth observable is defined as the sum of the jth element of each dict value (contribution from each meas basis). - Note the order of dict entries is relied on here for indexing; the dict keys are never used. - Assumes each Pauli term (in dict values) is compatible with each measurement basis (in keys). - Assumes each term in each observable appears for exactly one basis (TODO: remove this assumption).
• meas_basis_axis (int | None) – Axis of bool_array that indexes measurement bases. Ordering must match ordering in basis_dict. If None, then len(basis_dict) must be 1, and bool_array is assumed to correspond to the only measurement basis.
• avg_axis (int |tuple[int, ...] | None) – Optional axis or axes of bool_array to average over when computing expectation values. Usually this is the “twirling” axis. Must be nonnegative. (The shots axis, assumed to be at index -2 in the boolean array, is always averaged over).
• measurement_flips (ndarray[tuple[int, ...], dtype[bool]] | None) – Optional boolean array used with measurement twirling. Indicates which bits were acquired with measurements preceded by bit-flip gates. Data processing will use the result of xor`ing this array with `bool_array. Must be same shape as bool_array.
• pauli_signs (ndarray[tuple[int, ...], dtype[bool]] | None) – Optional boolean array used with probabilistic error cancellation (PEC). Final axis is assumed to index all noisy boxes in circuit. Value of True indicates an overall sign of -1 should be associated with the noisy box, typically because an odd number of inverse-noise errors were inserted in that box for the specified circuit randomization. The final axis is immediately collapsed as a sum mod 2 to obtain the overall sign associated with each circuit randomization. Remaining shape must be pauli_signs.shape[:-1] == bool_array.shape[:-2]. Note this array does not have a shots axis.
• postselect_mask (ndarray[tuple[int, ...], dtype[bool]] | None) – Optional boolean array used for postselection. True (False) indicates a shot accepted (rejected) by postselection. Shape must be bool_array.shape[:-1].
• gamma_factor (float | None) – Rescaling factor gamma to be applied to PEC mitigated expectation values. If None, rescaling factors will be computed as the number of positive samples minus the number of negative samples, computed as 1/(np.sum(~pauli_signs, axis=avg_axis) - np.sum(pauli_signs, axis=avg_axis)). This can fail due to division by zero if there are an equal number of positive and negative samples. Also note this rescales each expectation value by a different factor. (TODO: allow specifying an array of gamma values).
• rescale_factors (Sequence[Sequence[Sequence[float]]] | None) – Scale factor for each Pauli term in each observable in each basis in the given basis_dict. Typically used for readout mitigation (“TREX”) correction factors. Each item in the list corresponds to a different basis, and contains a list of lists of factors for each term in each observable related to that basis. The order of the bases and the observables inside each basis should be the same as in basis_dict. For empty observables for some of the bases, keep an empty list. If None, scaling factor will not be applied.

Returns

A list of (exp. val, variance) 2-tuples, one for each desired observable.

Note: Covariances between summed terms in each observable are not currently accounted for in the

returned variances. (TODO)

Raises

• ValueError if avg_axis contains negative values. –
• ValueError if meas_basis_axis is None but len**(basis_dict) **!= 1. –
• ValueError if the number** of entries in basis_dict does not equal the length of **bool_array along meas_basis_axis. –

get_measurement_bases(observables)

Choose bases to sample in order to calculate expectation values for all given observables.

Here a “basis” refers to measurement of a full-weight or high-weight Pauli, from which multiple qubit-wise commuting Paulis may be estimated.

The bases are chosen by grouping commuting Paulis across the different observables.

Parameters

observables (SparsePauliOp |list[SparsePauliOp]) – The observables to calculate using the quantum computer.

Returns

• List of Pauli bases to sample encoded in a list of uint8 where 0=I,1=Z,2=X,3=Y.
• Dict that maps each measured basis to the relevant Paulis and their coefficients for each observable. With the measured bases as keys, for each observable there is a SparsePauliOp representing it.

Return type

tuple[list[ndarray[tuple[int, …], dtype[uint8]]], dict[Pauli, list[SparsePauliOp]]]

map_observable_isa_to_canonical(isa_observable, canonical_qubits)

Map an observable defined relative to the transpiled circuit to canonical box-order.

In the transpiled (or ISA) ordering, the qubits are indexed based on the “physical” layout of qubits in the device.

For info on canonical qubit ordering conventions see the Samplomatic docs).

Parameters

• isa_observable (Pauli |SparsePauliOp |SparseObservable) – A Pauli, SparsePauliOp, or SparseObservable object.
• canonical_qubits (Sequence[int]) – A sequence specifying the physical qubit for each canonical qubit.

Returns

A mapped operator of the same type as isa_observable

Return type

Pauli | SparsePauliOp | SparseObservable

map_observable_virtual_to_canonical(virt_observable, layout, canonical_qubits)

Map an observable with virtual qubit ordering to canonical box-order.

For info on canonical qubit ordering conventions see the Samplomatic docs).

Parameters

• virt_observable (Pauli |SparsePauliOp |SparseObservable) – A Pauli, SparsePauliOp, or SparseObservable object.
• layout (Sequence[int]) – The list of physical qubits used for the isa circuit.
• canonical_qubits (Sequence[int]) – A dictionary mapping canonical qubits within a box to physical qubits within the layout.

Returns

A mapped operator of the same type as virt_observable

map_observable_isa_to_virtual(isa_observable, layout)

Map an observable defined relative to the transpiled circuit to virtual order.

In the transpiled (or ISA) ordering, the qubits are indexed based on the “physical” layout of qubits in the device.

Parameters

• isa_observable (Pauli |SparsePauliOp |SparseObservable) – A Pauli, SparsePauliOp, or SparseObservable object.
• layout (Sequence[int]) – The list of physical qubits used for the isa circuit.

Returns

A mapped operator of the same type as isa_observable

Return type

Pauli | SparsePauliOp | SparseObservable