Qiskit primitives give developers a consistent way to execute circuits, but Sampler, Estimator, and Qiskit Runtime solve different measurement and deployment problems. This guide explains how to choose between them, structure each workflow, interpret results, and check compatibility before moving from a local simulator to quantum hardware.
Overview
In a traditional quantum circuit tutorial, you build a circuit, run it, and inspect the result. Qiskit primitives make that process more structured by separating circuit construction from execution and measurement. The two core primitive families are:
- Sampler: use it when you need samples from a circuit’s measured output distribution, such as bitstrings, counts, or quasi-probabilities.
- Estimator: use it when you need the expected value of one or more observables, such as the energy of a Hamiltonian in a variational algorithm.
- Runtime primitives: use Qiskit Runtime when you want those workflows executed through an IBM Quantum service, especially for repeated, batched, or hardware-oriented experiments.
The exact class names and option structures can change between Qiskit releases. The examples below use the modern V2-style workflow as a conceptual baseline. Before copying code into a production project, check the documentation for the Qiskit and provider versions installed in your environment.
| Decision point | Sampler | Estimator | Runtime primitive |
|---|---|---|---|
| Primary input | Measured circuits | Circuits plus observables | Sampler or Estimator pubs submitted through a service |
| Primary output | Sampled bitstrings, counts, or distributions | Expectation values and uncertainty data | The corresponding primitive result from a remote backend |
| Shots | Central to the result; choose a shot count | Relevant when estimating noisy expectations; precision may also be specified | Controlled through primitive inputs and service-supported options |
| Observables | Not required | Required for expectation-value calculations | Required only when using Runtime Estimator |
| Batching | Submit multiple circuits or publications together | Submit circuit-observable pairs in one call | Designed for efficient remote submission and repeated workloads |
| Resilience options | Usually limited to sampling and backend behavior | May expose error-mitigation or resilience settings | Provider and backend dependent; inspect current Runtime options |
| Local simulation | Yes, with a local primitive or simulator | Yes, with a local primitive or simulator | Generally requires a configured provider and service backend |
| Typical use | Sampling, classifiers, search circuits, distribution analysis | VQE, QAOA objectives, Hamiltonian measurements, benchmarking | Hardware experiments and production-like remote workflows |
Checklist by scenario
Use Sampler for measurement distributions
Choose Sampler when the meaning of your experiment is contained in the measured bitstrings. This is common for a quantum circuit tutorial, a Grover-style search experiment, a sampling-based classifier, or any algorithm where you want to compare output frequencies.
- Build a circuit with measurements. A sampler does not infer the measurement you intended; add the appropriate classical registers and measurement operations.
- Select a local Sampler implementation for fast development, or a provider-backed Sampler for hardware execution.
- Submit one or more circuits with a shot count.
- Read the result data for each submitted circuit and calculate frequencies or probabilities in your application code.
from qiskit import QuantumCircuit
from qiskit.primitives import StatevectorSampler
circuit = QuantumCircuit(2)
circuit.h(0)
circuit.cx(0, 1)
circuit.measure_all()
sampler = StatevectorSampler()
job = sampler.run([circuit], shots=1024)
result = job.result()[0]
counts = result.data.meas.get_counts()
print(counts)
The precise data container can vary by primitive implementation and release. The important interpretation is that the counts are finite samples, not exact probabilities. Increase shots when you need a more stable estimate, and record the shot count with your experiment.
Use Estimator for observable values
Choose Estimator when your question is mathematical rather than distributional: “What is the expectation value of this operator in the state prepared by my circuit?” This is the natural pattern for variational quantum eigensolvers, QAOA objective functions, and Hamiltonian measurements.
- Prepare a circuit that creates the state of interest. Do not add final measurements solely for the Estimator workflow.
- Represent the observable with a supported operator format, such as a Pauli sum.
- Submit circuit-observable pairs, optionally with parameter values.
- Read the expectation value and uncertainty information, then use it in your optimizer or analysis pipeline.
from qiskit import QuantumCircuit
from qiskit.quantum_info import SparsePauliOp
from qiskit.primitives import StatevectorEstimator
circuit = QuantumCircuit(2)
circuit.h(0)
circuit.cx(0, 1)
observable = SparsePauliOp.from_list([("ZZ", 1.0)])
estimator = StatevectorEstimator()
job = estimator.run([(circuit, observable)])
result = job.result()[0]
print(result.data.evs)
print(result.data.stds)
For parameterized circuits, include the parameter values using the input structure expected by your installed Estimator V2 implementation. Keep the observable’s qubit order aligned with the circuit, and verify sign conventions before interpreting an energy or cost value.
Use Runtime for remote hardware workflows
Runtime is a service execution layer, not a third kind of measurement. Its Sampler and Estimator primitives apply the same basic distinction to a provider-managed backend. A typical workflow is:
- Install a compatible
qiskitandqiskit-ibm-runtimecombination. - Authenticate and select a backend through
QiskitRuntimeService. - Construct
SamplerV2orEstimatorV2with the current Runtime interface. - Transpile circuits for the selected backend before submission when required by the workflow.
- Set supported shot, precision, batching, and resilience options deliberately rather than relying on defaults.
- Save the backend name, primitive version, options, transpilation settings, and job identifier with the result.
Provider authentication, backend selection, session or batch modes, and resilience configuration are version-sensitive. Treat the Runtime API reference for your installed release as authoritative instead of copying an older example that uses deprecated provider or option names.
What to double-check
- Primitive generation: confirm whether your environment exposes V1, V2, or a local implementation. V2 result containers and input “publication” structures differ from older examples.
- Measurement requirements: Sampler circuits normally need measurements; Estimator circuits normally use observables directly.
- Shot semantics: a Sampler’s counts are sampled data. An Estimator’s value is an estimate with uncertainty, not an exact symbolic result.
- Parameter binding: verify parameter order and the shape of parameter-value arrays before batching many circuit evaluations.
- Observable layout: check Pauli-string length, qubit ordering, coefficients, and whether an identity term is included.
- Backend compatibility: confirm supported instructions, qubit count, connectivity, calibration constraints, and whether the selected backend accepts your primitive workflow.
- Transpilation: compare logical and transpiled circuits before interpreting hardware results. The Qiskit transpilation guide provides a useful review checklist.
- Reproducibility: record seeds where supported, shots, software versions, backend, observables, and optimizer settings. For broader testing guidance, see how to test quantum programs.
Common mistakes
Using Sampler for an expectation-value objective. You can reconstruct an expectation from counts, but that adds manual bookkeeping and can obscure uncertainty. Use Estimator when the observable is the primary result.
Adding measurements to every circuit. Measurements are appropriate for Sampler, but an Estimator generally evaluates observables without requiring final measurement instructions. Mixing the two patterns can produce confusing inputs or invalid workflows.
Assuming local and hardware results are interchangeable. A statevector simulator can provide an ideal reference, while hardware introduces noise, readout effects, connectivity constraints, and transpilation changes. Use a noisy simulator or repeated hardware trials when validating a realistic workflow. The error mitigation overview explains the trade-offs.
Copying Runtime options from an old tutorial. Names such as resilience settings, execution mode, and backend selection have changed across releases. Check signatures, warnings, and provider documentation in the environment you actually run.
Ignoring statistical uncertainty. A small difference between two objective values may be sampling or hardware noise rather than an algorithmic improvement. Repeat important evaluations and compare uncertainty alongside the central value.
When to revisit
Revisit this checklist whenever you start a new experiment, convert a circuit from Sampler to Estimator, move from local simulation to cloud quantum computing, or upgrade Qiskit or a provider package. A quarterly compatibility review is a practical minimum for maintained projects; review sooner when release notes mention primitives, Runtime options, result containers, backend support, or transpilation changes.
Before each hardware run, use this short action list:
- State whether the output you need is a distribution or an expectation value.
- Choose Sampler or Estimator accordingly, then select local or Runtime execution.
- Check the installed API and update imports and result parsing if necessary.
- Validate measurements, observables, parameter shapes, shots or precision, and batching.
- Transpile and inspect the circuit for the target backend.
- Run a small test, save metadata, and compare results against an ideal or known reference.
That process keeps a Qiskit primitives tutorial useful beyond a single code sample: the measurement model stays stable even as implementation details, backends, and Runtime interfaces evolve.