Utils

load_tasks_from_result(result, return_trex=False)

Load MitigationTask objects from an execution result using the passthrough_data saved in the result.

Parameters

• result (QuantumProgramResult) – The resul object to load the tasks from.
• return_trex (bool) – If True, include TREX calibration element in the returned list of MitigationTask objects.

Returns

List of MitigationTask objects that created the program of the given result.

Return type

list[MitigationTask]

find_combined_unique_layers(circuits, mitigation_types=None, custom_boxing_options=None, box_types='all')

Return the unique boxed layers found across the given circuits using the given boxing options.

The returned list contains one instance of each distinct boxed layer (represented as a CircuitInstruction) appearing in the input circuits. Some mitigation methods enforce relevant boxing options. By supllying the wanted mitigation methods, these options are enforced when boxing the circuits to find unique layers. Supplying the wanted mitigation methods is recommended to ensure that the unique layers used for learning wiil be equal to those used in execution. The returned boxes can be filtered so only boxes containing measurements, only boxes containing solely gates or all types of boxes are returned.

Parameters

• circuits (list[QuantumCircuit]) – The circuit to find the unique layers for.
• mitigation_types (list[MitigationTask] | None) – List of initiated mitigation classes that the circuits will be mitigated with. Each mitigation method might enforce boxing options that will affect the unique layers. If given, the list must be the same length as circuits.
• custom_boxing_options (dict |list[dict] | None) – The custom boxing options that will be used by generate_boxing_pass_manager() function to find the unique layers. If a single dict is given, the same custom boxing option will be used for all tasks. If None is given, the default boxing option will be used.
• box_types (Literal['gates', 'measurement', 'all']) – Can be either "gates", "measurements" or "all", corresponding to filter boxes with only gate layers, only measurement layers or all layers, respectively.

Returns

Unique boxed layers found across the given circuits using the given boxing options.

Return type

list[CircuitInstruction]

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)

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_mapping, to compute observables encoded in values of basis_mapping.

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_mapping).

• basis_mapping (dict[Pauli, list[SparsePauliOp | None]] |tuple[Sequence[SparsePauliOp], Sequence[str] | 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 | 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 |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 (dict[str, float] | None) – Scale factor for each unique Pauli term found in the calculated observables. Typically used for readout mitigation (“TREX”) correction factors. 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 – avg_axis contains negative values, repeated axes, or one of the last two (shots, bits) axes.
• ValueError – avg_axis contains meas_basis_axis.
• ValueError – meas_basis_axis is None but len(basis_mapping) != 1.
• ValueError – meas_basis_axis is negative or indexes one of the last two (shots, bits) axes of bool_array.
• ValueError – The number of entries in basis_mapping does not equal the length of bool_array along meas_basis_axis.
• ValueError – An observable is not covered by the measurement bases.

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[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 sequence specifying the physical qubit for each canonical qubit.

Returns

A mapped operator of the same type as virt_observable

Return type

Pauli | SparsePauliOp | SparseObservable

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