---
title: exp_vals (latest version)
description: API reference for qiskit_addon_utils.exp_vals in the latest version of qiskit-addon-utils
source: https://eu-de.quantum.cloud.ibm.com/docs/en/api/qiskit-addon-utils/exp-vals
---

# exp\_vals

`qiskit_addon_utils.exp_vals`

Tools for calculating expectation values.

### executor\_expectation\_values

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

[GitHub](https://github.com/Qiskit/qiskit-addon-utils/tree/stable/0.4/qiskit_addon_utils/exp_vals/expectation_values.py#L24-L202)

Computes expectation values from shot data from `qiskit_ibm_runtime.Executor` and metadata.

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*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray)*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple)*\[*[*int*](https://docs.python.org/3/library/functions.html#int)*, ...],* [*dtype*](https://numpy.org/doc/stable/reference/generated/numpy.dtype.html#numpy.dtype)*\[*[*bool*](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.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_mapping)`.

- **basis\_mapping** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict)*\[*[*Pauli*](/docs/api/qiskit/qiskit.quantum_info.Pauli)*,* [*list*](https://docs.python.org/3/library/stdtypes.html#list)*\[*[*SparsePauliOp*](/docs/api/qiskit/qiskit.quantum_info.SparsePauliOp)  *| None]] |*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple)*\[*[*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)*\[*[*SparsePauliOp*](/docs/api/qiskit/qiskit.quantum_info.SparsePauliOp)*],* [*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str)*] |* [*PauliList*](/docs/api/qiskit/qiskit.quantum_info.PauliList)*]*) –

  The Pauli observables and associated bases which were measured. Can be a `tuple`, `(observables, msmt_bases)`, or a `dict`, `{basis: commuting_observables}`.

  - **tuple**: A length-2 tuple containing `(observables, msmt_bases)`, where `observables` is a sequence of `SparsePauliOp` instances for which individual expectation values should be calculated, and `msmt_bases` is a sequence of Pauli observables. The `i` th Pauli in `msmt_bases` is expected to correspond to the `i` th slice of `bool_array` along the `meas_basis_axis`.
  - **dict**: The `i` th key is a measurement basis assumed to correspond to the `i` th slice of `bool_array` along the `meas_basis_axis` axis. The values are lists of observables (`SparsePauliOp`) with length equal to the number of observables. `None` values are used when an observable does not qubit-wise commute with the basis. This method assumes each observable appears only once in the values, even if it commutes with more than one basis.

- **meas\_basis\_axis** ([*int*](https://docs.python.org/3/library/functions.html#int) *| None*) – Axis of bool\_array that indexes measurement bases. Ordering must match ordering in `basis_mapping`. If `None`, then `len(basis_mapping)` must be `1`, and `bool_array` is assumed to correspond to the only measurement basis.

- **avg\_axis** ([*int*](https://docs.python.org/3/library/functions.html#int)  *|*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple)*\[*[*int*](https://docs.python.org/3/library/functions.html#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*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray)*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple)*\[*[*int*](https://docs.python.org/3/library/functions.html#int)*, ...],* [*dtype*](https://numpy.org/doc/stable/reference/generated/numpy.dtype.html#numpy.dtype)*\[*[*bool*](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.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*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray)*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple)*\[*[*int*](https://docs.python.org/3/library/functions.html#int)*, ...],* [*dtype*](https://numpy.org/doc/stable/reference/generated/numpy.dtype.html#numpy.dtype)*\[*[*bool*](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.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*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray)*\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple)*\[*[*int*](https://docs.python.org/3/library/functions.html#int)*, ...],* [*dtype*](https://numpy.org/doc/stable/reference/generated/numpy.dtype.html#numpy.dtype)*\[*[*bool*](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.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*](https://docs.python.org/3/library/functions.html#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*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)*\[*[*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)*\[*[*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)*\[*[*float*](https://docs.python.org/3/library/functions.html#float)*]]] | None*) – Scale factor for each Pauli term in each observable in each basis in the given `basis_mapping`. 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_mapping`. 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**](https://docs.python.org/3/library/exceptions.html#ValueError) – `avg_axis` contains negative values.
- [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – `meas_basis_axis` is `None` but `len(basis_mapping) != 1`.
- [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – The number of entries in `basis_mapping` does not equal the length of `bool_array` along `meas_basis_axis`.
- [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – An observable is not covered by the measurement bases.

### get\_measurement\_bases

`get_measurement_bases(observables, bases_in_int_format=True)`

[GitHub](https://github.com/Qiskit/qiskit-addon-utils/tree/stable/0.4/qiskit_addon_utils/exp_vals/measurement_bases.py#L21-L71)

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*](/docs/api/qiskit/qiskit.quantum_info.SparsePauliOp)  *|*[*list*](https://docs.python.org/3/library/stdtypes.html#list)*\[*[*SparsePauliOp*](/docs/api/qiskit/qiskit.quantum_info.SparsePauliOp)*]*) – The observables to calculate using the quantum computer.
- **bases\_in\_int\_format** ([*bool*](https://docs.python.org/3/library/functions.html#bool)) – If true, return bases as an array of ints, using the samplomatic convention of: I=0, Z=1, X=2, Y=3. The order of the ints will be according to the index of each Pauli in the string. For example, the basis “IXYZ” would be returned as \[1, 3, 2, 0]. If false, return the bases as an array of strings.

**Returns**

- List of Pauli bases to sample encoded in a list of uint8 where 0=I,1=Z,2=X,3=Y or a list of strings (based on bases\_in\_int\_format parameter).
- 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](https://docs.python.org/3/library/stdtypes.html#tuple)\[[list](https://docs.python.org/3/library/stdtypes.html#list)\[[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray)\[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple)\[[int](https://docs.python.org/3/library/functions.html#int), …], [*dtype*](https://numpy.org/doc/stable/reference/generated/numpy.dtype.html#numpy.dtype)\[*uint8*]]], [dict](https://docs.python.org/3/library/stdtypes.html#dict)\[[*Pauli*](/docs/api/qiskit/qiskit.quantum_info.Pauli), [list](https://docs.python.org/3/library/stdtypes.html#list)\[[*SparsePauliOp*](/docs/api/qiskit/qiskit.quantum_info.SparsePauliOp)]]] | [tuple](https://docs.python.org/3/library/stdtypes.html#tuple)\[[list](https://docs.python.org/3/library/stdtypes.html#list)\[[str](https://docs.python.org/3/library/stdtypes.html#str)], [dict](https://docs.python.org/3/library/stdtypes.html#dict)\[[*Pauli*](/docs/api/qiskit/qiskit.quantum_info.Pauli), [list](https://docs.python.org/3/library/stdtypes.html#list)\[[*SparsePauliOp*](/docs/api/qiskit/qiskit.quantum_info.SparsePauliOp)]]]

### map\_observable\_isa\_to\_canonical

`map_observable_isa_to_canonical(isa_observable, canonical_qubits)`

[GitHub](https://github.com/Qiskit/qiskit-addon-utils/tree/stable/0.4/qiskit_addon_utils/exp_vals/observable_mappings.py#L22-L69)

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](https://qiskit.github.io/samplomatic/guides/samplex_io.html#qubit-ordering-convention)).

**Parameters**

- **isa\_observable** ([*Pauli*](/docs/api/qiskit/qiskit.quantum_info.Pauli)  *|*[*SparsePauliOp*](/docs/api/qiskit/qiskit.quantum_info.SparsePauliOp)  *|*[*SparseObservable*](/docs/api/qiskit/qiskit.quantum_info.SparseObservable)) – A Pauli, SparsePauliOp, or SparseObservable object.
- **canonical\_qubits** ([*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)*\[*[*int*](https://docs.python.org/3/library/functions.html#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*](/docs/api/qiskit/qiskit.quantum_info.Pauli) | [*SparsePauliOp*](/docs/api/qiskit/qiskit.quantum_info.SparsePauliOp) | [*SparseObservable*](/docs/api/qiskit/qiskit.quantum_info.SparseObservable)

### map\_observable\_virtual\_to\_canonical

`map_observable_virtual_to_canonical(virt_observable, layout, canonical_qubits)`

[GitHub](https://github.com/Qiskit/qiskit-addon-utils/tree/stable/0.4/qiskit_addon_utils/exp_vals/observable_mappings.py#L72-L125)

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

For info on canonical qubit ordering conventions see the [Samplomatic docs](https://qiskit.github.io/samplomatic/guides/samplex_io.html#qubit-ordering-convention)).

**Parameters**

- **virt\_observable** ([*Pauli*](/docs/api/qiskit/qiskit.quantum_info.Pauli)  *|*[*SparsePauliOp*](/docs/api/qiskit/qiskit.quantum_info.SparsePauliOp)  *|*[*SparseObservable*](/docs/api/qiskit/qiskit.quantum_info.SparseObservable)) – A Pauli, SparsePauliOp, or SparseObservable object.
- **layout** ([*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)*\[*[*int*](https://docs.python.org/3/library/functions.html#int)*]*) – The list of physical qubits used for the isa circuit.
- **canonical\_qubits** ([*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)*\[*[*int*](https://docs.python.org/3/library/functions.html#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

`map_observable_isa_to_virtual(isa_observable, layout)`

[GitHub](https://github.com/Qiskit/qiskit-addon-utils/tree/stable/0.4/qiskit_addon_utils/exp_vals/observable_mappings.py#L128-L174)

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*](/docs/api/qiskit/qiskit.quantum_info.Pauli)  *|*[*SparsePauliOp*](/docs/api/qiskit/qiskit.quantum_info.SparsePauliOp)  *|*[*SparseObservable*](/docs/api/qiskit/qiskit.quantum_info.SparseObservable)) – A Pauli, SparsePauliOp, or SparseObservable object.
- **layout** ([*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)*\[*[*int*](https://docs.python.org/3/library/functions.html#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*](/docs/api/qiskit/qiskit.quantum_info.Pauli) | [*SparsePauliOp*](/docs/api/qiskit/qiskit.quantum_info.SparsePauliOp) | [*SparseObservable*](/docs/api/qiskit/qiskit.quantum_info.SparseObservable)