---
title: PEC (latest version)
description: API reference for qiskit_mitigation.PEC in the latest version of qiskit-mitigation
source: https://quantum.cloud.ibm.com/docs/en/api/qiskit-mitigation/pec
---

# PEC (`qiskit_mitigation.pec`)

### PEC

*class* `PEC`

[GitHub](https://github.com/Qiskit/qiskit-mitigation/tree/stable/0.1/qiskit_mitigation/pec.py#L48-L700)

Bases: [`MitigationTask`](/docs/api/qiskit-mitigation/mitigation-task#qiskit_mitigation.MitigationTask "qiskit_mitigation.mitigation_task.MitigationTask")

Calculates expectation values of observables using Probabilistic Error Cancellation (PEC) mitigation method.

The class enables preparing a QuantumProgram with circuit mitigated using PEC method, that can be executed on hardware using the Executor, and post process the results to calculate mitigated expectation values of given observables. The task parameters should be given as input to the prepare function, and the relevant variables needed for post-processing are saved internally:

```python
pec = PEC()
program = pec.prepare(circuit=circuit,
                      observables=observables,
                      parameters=parameter_valuesת
                      noise_maps=learned_noise)
job = executor.run(program)
results = job.result()
mitigated_result = pec.postprocess(results)
```

To calculate expectation values of a loaded job result, a PEC task can be created from the job results with all the internal variables needed for post-processing. Alternatively, the variables required for post-processing can be given as input directly to the `compute_expectation_value` static method. Example for running post-processing for a loaded result:

```python
pec = PEC()
program = pec.prepare(circuit=circuit,
                      observables=observables,
                      parameters=parameter_valuesת
                      noise_maps=learned_noise)
job_id = executor.run(program).job_id

job = service.job(job_id)
results = job.result()
pec = load_tasks_from_result(results)[0]
mitigated_result = pec.postprocess(results)
```

Instantiate a PEC task.

#### Methods

##### find\_unique\_layers

`find_unique_layers(circuit, custom_boxing_options=None)`

[GitHub](https://github.com/Qiskit/qiskit-mitigation/tree/stable/0.1/qiskit_mitigation/mitigation_task.py#L566-L586)

Return the unique boxed layers of the given circuit using the given boxing options.

**Parameters**

- **circuit** ([*QuantumCircuit*](/docs/api/qiskit/qiskit.circuit.QuantumCircuit)) – The circuit to found its unique layers.
- **custom\_boxing\_options** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict) *| None*) – The custom boxing options that will be used by `generate_boxing_pass_manager()` function.

**Returns**

Unique boxed layers of the given circuit.

**Return type**

[list](https://docs.python.org/3/builtins/stdtypes.html#list)\[[*CircuitInstruction*](/docs/api/qiskit/qiskit.circuit.CircuitInstruction)]

##### prepare

`prepare(circuit, observables, parameters, custom_boxing_options=None, shots_per_randomization=64, num_randomizations=128, broadcast_obs_and_params=False, trex=None, quantum_program=None, *, noise_maps=None, scale_randomizations_by_gamma=True, noise_gain='auto', max_sampling_overhead=100)`

[GitHub](https://github.com/Qiskit/qiskit-mitigation/tree/stable/0.1/qiskit_mitigation/pec.py#L146-L341)

Creates a `QuantumProgram` with PEC mitigated item for executing via Executor.

Creates an item for a `QuantumProgram`, that can be executed via Executor and is PEC mitigated (injects inverse noise to cancel the learned noise). If a `quantum_program` is provided, the new item will be added to the existing program, otherwise, a new program will be created, containing only the created item. If `broadcast_obs_and_params` is True, the observables and parameters will be broadcasted using the samplomatic broadcasting rules, to allow attaching some of the parameters to some of the observables. Otherwise, every parameter will be executed for each observable (outer product of the parameters and observables). Note that the post-processing of an outer product is usually faster.

**Parameters**

- **circuit** ([*QuantumCircuit*](/docs/api/qiskit/qiskit.circuit.QuantumCircuit)) – The quantum circuit.
- **observables** ([*ObservablesArray*](/docs/api/qiskit/qiskit.primitives.ObservablesArray)  *|*[*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)*\[*[*SparsePauliOp*](/docs/api/qiskit/qiskit.quantum_info.SparsePauliOp)*]*) – The observables to calculate their expectation values.
- **parameters** ([*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray)  *|*[*BindingsArray*](/docs/api/qiskit/qiskit.primitives.BindingsArray) *| None*) – The parameters of a parametric circuit.
- **custom\_boxing\_options** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict) *| None*) – The custom boxing options that will be used by `generate_boxing_pass_manager()` function.
- **shots\_per\_randomization** ([*int*](https://docs.python.org/3/builtins/functions.html#int)) – The number of shots per randomization.
- **num\_randomizations** ([*int*](https://docs.python.org/3/builtins/functions.html#int)) – The number of randomizations.
- **broadcast\_obs\_and\_params** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to broadcast observables and parameters.
- **trex** ([*TREX*](/docs/api/qiskit-mitigation/trex#qiskit_mitigation.TREX "qiskit_mitigation.trex.TREX") *| None*) – A TREX mitigation instance that will be used to mitigate readout errors.
- **quantum\_program** ([*QuantumProgram*](https://qiskit.github.io/samplomatic/api/auto/samplomatic.quantum_program.QuantumProgram.html#samplomatic.quantum_program.QuantumProgram "(in samplomatic)") *| None*) – The quantum program to add an item for. If None, a new program will be created.
- **noise\_maps** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)*\[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str)*,* [*PauliLindbladMap*](/docs/api/qiskit/qiskit.quantum_info.PauliLindbladMap)*] | None*) – A mapping between layer ref to a noise model to use for PEC mitigation method. The dict might contain layers not present in the given circuit, but must contain all the mitigated layers. Assumes that the unique layers used for noise learning were extracted using the `find_unique_layers` method with the same custom boxing options.
- **scale\_randomizations\_by\_gamma** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to automatically scale the number of randomizations by gamma\*\*2.
- **noise\_gain** ([*float*](https://docs.python.org/3/builtins/functions.html#float)  *|*[*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal)*\['auto']*) – The fraction of noise to keep after the mitigation. A value of `0` corresponds to removing the full learned noise. A value of `1` corresponds to no removal of the learned noise. A value between `0` and `1` corresponds to partially removing the learned noise. A value greater than one corresponds to amplifying the learned noise. If `"auto"`, the value in the range `[0, 1]` will be chosen automatically by the formula `1 - log(max_overhead) / log(gamma^2)`.
- **max\_sampling\_overhead** ([*float*](https://docs.python.org/3/builtins/functions.html#float) *| None*) – If scale\_randomizations\_by\_gamma is True, limit the multiplicative ratio of the number of randomizations.

**Returns**

A `QuantumProgram` with PEC mitigated item that can be executed via Executor.

**Return type**

[*QuantumProgram*](https://qiskit.github.io/samplomatic/api/auto/samplomatic.quantum_program.QuantumProgram.html#samplomatic.quantum_program.QuantumProgram "(in samplomatic)")

##### postprocess

`postprocess(results, measure_noise_data=None)`

[GitHub](https://github.com/Qiskit/qiskit-mitigation/tree/stable/0.1/qiskit_mitigation/pec.py#L343-L380)

Process expectation values for a single pec mitigated item result.

**Parameters**

- **results** ([*QuantumProgramItemResult*](https://qiskit.github.io/samplomatic/api/auto/samplomatic.quantum_program.QuantumProgramItemResult.html#samplomatic.quantum_program.QuantumProgramItemResult "(in samplomatic)")  *|*[*QuantumProgramResult*](https://qiskit.github.io/samplomatic/api/auto/samplomatic.quantum_program.QuantumProgramResult.html#samplomatic.quantum_program.QuantumProgramResult "(in samplomatic)")) – The execution results. Can be either the entire results object or the pec mitigated item result of this task. If TREX calibration task is added to the quantum program, its results will be used to compute the measure noise data if the entire results object is provided.
- **measure\_noise\_data** ([*PauliLindbladMap*](/docs/api/qiskit/qiskit.quantum_info.PauliLindbladMap)  *|*[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray) *| None*) – The learned measurement noise data to use for TREX mitigation. If None and a calibration task is present the quantum program, the measure noise will be computed from the calibration task results if the entire results object is provided.

**Returns**

A PubResult which contains `evs` and `std` as fields in its data, where `evs` are expectation values, and `std` are the standard deviation of the expectation values. If `broadcast_obs_and_params` is set to True, the data will contain also a `twirl_stds` field which is the standard deviation between different randomizations.

**Raises**

- [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError) – If the task’s item result has no `'_meas'` key.
- [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError) – If the item result’s `'_meas'` data has an invalid number of axes.
- [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError) – If `param_shape` and `observables.shape` cannot be broadcasted against each other, while `broadcast_obs_and_params` was set to `True` in the task preparation.

**Return type**

[*PubResult*](/docs/api/qiskit/qiskit.primitives.PubResult)

##### compute\_expectation\_value\_pec

*static* `compute_expectation_value_pec(item_result, observables, gamma, param_shape=None, param_basis_pairs=None, meas_bases=None, broadcast_obs_and_params=False, measure_noise_data=None)`

[GitHub](https://github.com/Qiskit/qiskit-mitigation/tree/stable/0.1/qiskit_mitigation/pec.py#L581-L700)

Process expectation values for a single pec mitigated item result.

This function can be used to calculate expectation values for a single pec mitigated item result without instantiating a new class instance.

**Parameters**

- **item\_result** ([*QuantumProgramItemResult*](https://qiskit.github.io/samplomatic/api/auto/samplomatic.quantum_program.QuantumProgramItemResult.html#samplomatic.quantum_program.QuantumProgramItemResult "(in samplomatic)")) – The item result.
- **observables** ([*ObservablesArray*](/docs/api/qiskit/qiskit.primitives.ObservablesArray)  *|*[*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)*\[*[*SparsePauliOp*](/docs/api/qiskit/qiskit.quantum_info.SparsePauliOp)*]*) – The observables to calculate expectation values for.
- **gamma** ([*float*](https://docs.python.org/3/builtins/functions.html#float)) – The gamma factor of the learned noise model for the executed circuit.
- **param\_shape** ([*tuple*](https://docs.python.org/3/builtins/stdtypes.html#tuple)*\[*[*int*](https://docs.python.org/3/builtins/functions.html#int)*, ...] | None*) – The shape of the parameter values.
- **param\_basis\_pairs** ([*list*](https://docs.python.org/3/builtins/stdtypes.html#list)*\[*[*tuple*](https://docs.python.org/3/builtins/stdtypes.html#tuple)*\[*[*tuple*](https://docs.python.org/3/builtins/stdtypes.html#tuple)*\[*[*int*](https://docs.python.org/3/builtins/functions.html#int)*, ...],* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str)*]] | None*) – The map between params ndindexes to measure basis.
- **meas\_bases** ([*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)*\[*[*Pauli*](/docs/api/qiskit/qiskit.quantum_info.Pauli)*] |* [*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)*\[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str)*] |* [*PauliList*](/docs/api/qiskit/qiskit.quantum_info.PauliList) *| None*) – A list of the measured Pauli bases. The `i` th item is a measurement basis assumed to correspond to the `i` th slice of the data in `item_result`.
- **broadcast\_obs\_and\_params** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to broadcast observables and parameter values.
- **measure\_noise\_data** ([*PauliLindbladMap*](/docs/api/qiskit/qiskit.quantum_info.PauliLindbladMap)  *|*[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray) *| None*) – Measurement noise calibration data for TREX mitigation.

**Returns**

A PubResult which contains `evs` and `std` as fields in its data, where `evs` are expectation values, and `std` are the standard deviation of the expectation values. If `broadcast_obs_and_params` is set to True, the data will contain also a `twirl_stds` field which is the standard deviation between different randomizations.

**Raises**

- [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError) – If `item_result` has no `'_meas'` key.
- [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError) – If `item_result['_meas']` has invalid number of axes.
- [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError) – If `item_result` has no `'pauli_signs'` key.
- [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError) – If `param_shape` and `observables.shape` cannot be broadcasted against each other.

**Return type**

[*PubResult*](/docs/api/qiskit/qiskit.primitives.PubResult)

##### create\_instance\_from\_passthrough\_data

*static* `create_instance_from_passthrough_data(passthrough, trex=None)`

[GitHub](https://github.com/Qiskit/qiskit-mitigation/tree/stable/0.1/qiskit_mitigation/pec.py#L538-L579)

Create a PEC instance from a passthrough dictionary loaded from a quantum program execution result.

**Parameters**

- **passthrough** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)*\[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str)*,* [*Any*](https://docs.python.org/3/library/typing.html#typing.Any)*]*) – Passthrough\_data dictionary loaded from a quantum program execution result.
- **trex** ([*TREX*](/docs/api/qiskit-mitigation/trex#qiskit_mitigation.TREX "qiskit_mitigation.trex.TREX") *| None*) – A TREX instance containing a calibration circuit results executed in the same quantum program. Should remain `None` in case TREX mitigation was not used or a TREX calibration was not executed as part of thq same quantum program.

**Returns**

A PEC instance.

**Return type**

[*PEC*](#qiskit_mitigation.PEC "qiskit_mitigation.pec.PEC")