Estimator
class Estimator(mode=None, options=None)
Bases: BaseEstimatorV2
Client-side Estimator primitive for IBM Quantum Compute (formerly Qiskit Runtime).
This is an implementation of Estimator built on top of the Executor primitive, enabling transparent client-side processing with faster feedback loops and greater user control.
Example
from qiskit import QuantumCircuit
from qiskit.quantum_info import SparsePauliOp
from qiskit_ibm_runtime import QiskitRuntimeService
from qiskit_ibm_runtime.executor_estimator import Estimator
service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)
# Create a simple circuit
circuit = QuantumCircuit(2)
circuit.h(0)
circuit.cx(0, 1)
# Define observable
observable = SparsePauliOp.from_list([("ZZ", 1), ("XX", 1)])
# Run the estimator with options
estimator = Estimator(mode=backend)
estimator.options.default_precision = 0.01
estimator.options.execution.init_qubits = True
job = estimator.run([(circuit, observable)])
result = job.result()Parameters
-
mode (BackendV2 | Session |Batch | None) –
The execution mode used to make the primitive query. It can be:
- A
BackendV2if you are using job mode. - A
Sessionif you are using session execution mode. - A
Batchif you are using batch execution mode.
Refer to the IBM Quantum Compute documentation for more information about execution modes.
- A
-
options (EstimatorOptions) – Estimator options. See
EstimatorOptionsfor all available options.
Attributes
mode
Return the execution mode used by this primitive.
Returns
Mode used by this primitive, or None if an execution mode is not used.
options
Type: EstimatorOptions
The options of this Estimator.
Methods
backend
finalize_options
finalize_options()
Construct and finalize the Estimator options.
This method combines the configured resilience level with the user-provided option to produce the final EstimatorOptions instance used inside a call to run().
The process used to produce the finalized options is as follows:
-
Initialize a new
EstimatorOptionsobject with defaults determined byresilience_level. -
Apply user-specified options, skipping the fields left as
Nonethat are intended to inherit the resilience-level defaults. -
Enforce required option dependencies. Specifically:
- Enabling measurement mitigation automatically enables measurement twirling.
- Enabling gate-based mitigation techniques (such as PEA-based ZNE or PEC) automatically enables both gate and measurement twirling.
Returns
The finalized EstimatorOptions object.
Return type
find_unique_layers
find_unique_layers(pubs, types='gates')
Return the unique boxed layers found across the given PUBs.
The types of layers can be either "gates" or "all", corresponding to only gate layers or all layers, respectively. The returned list then contains one instance of each distinct boxed layer (represented as a CircuitInstruction) appearing in the input PUBs.
For example, for noise learning, keep only the qubit gate layers:
est = Estimator(mode, options)
est.options.resilience.pec_mitigation = True
layers = est.find_unique_layers(pubs, types="gates")
results = NoiseLearnerV3(mode).run(layers).result()
pauli_linblad_maps = results.to_pauli_lindblad_maps()
# Assign the learned model so PEC uses it on the next run.
est.options.resilience.layer_noise_model = zip(layers, pauli_linblad_maps)Parameters
- pubs (Iterable[EstimatorPubLike]) – The list of PUBs to return a list of unique boxes for.
- types (Literal['gates', 'all']) – The types of layers to return. Can be either
"gates"or"all".
Returns
The unique boxed layers of a certain type found across the given PUBs.
Return type
list[CircuitInstruction]
run
run(pubs, *, precision=None, dry_run=False)
Submit a request to the estimator primitive.
For moderate and complex workloads, the client-side processing done to map estimator inputs to executor inputs can be resource intensive and cause a delay between invoking the function and the job being submitted. In order to check the progress of the call, it is recommended to setup logging (with an INFO level) - see IBM Quantum Compute documentation for more information.
Parameters
- pubs (Iterable[EstimatorPubLike]) – An iterable of pub-like objects. For example, a list of circuits and observables or tuples
(circuit, observables, parameter_values). - precision (float | None) – The target precision for expectation value estimates of each estimator pub that does not specify its own precision. If
None, the value fromoptions.default_precisionwill be used. - dry_run (bool) – If
True, performs a dry run without executing the job on a QPU. This mode can be used to validate the job, estimate usage consumption, and retrieve circuit timing metadata. Returned results preserve the expected schema but contain randomized mock data rather than actual or simulated measurement results. Unlike the fake backends, the processing of this dry run happens on the server-side, so the job may not finish immediately and access to this feature may be restricted.
Returns
The submitted job.
Raises
- ValueError – If backend is not provided.
- IBMInputValueError – If no pubs are provided, if precision is not properly specified, or if unsupported options are detected.
Return type
RuntimeJobV2 | LocalRuntimeJob