Qiskit Primitives Explained: Sampler, Estimator, and Runtime Workflows for Developers
QiskitQuantum PrimitivesEstimatorSamplerQiskit Runtime

Qiskit Primitives Explained: Sampler, Estimator, and Runtime Workflows for Developers

JJustQubit Editorial Team
2026-11-16
6 min read

Choose Qiskit Sampler, Estimator, or Runtime with practical workflows, comparison guidance, code patterns, and upgrade checks.

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 pointSamplerEstimatorRuntime primitive
Primary inputMeasured circuitsCircuits plus observablesSampler or Estimator pubs submitted through a service
Primary outputSampled bitstrings, counts, or distributionsExpectation values and uncertainty dataThe corresponding primitive result from a remote backend
ShotsCentral to the result; choose a shot countRelevant when estimating noisy expectations; precision may also be specifiedControlled through primitive inputs and service-supported options
ObservablesNot requiredRequired for expectation-value calculationsRequired only when using Runtime Estimator
BatchingSubmit multiple circuits or publications togetherSubmit circuit-observable pairs in one callDesigned for efficient remote submission and repeated workloads
Resilience optionsUsually limited to sampling and backend behaviorMay expose error-mitigation or resilience settingsProvider and backend dependent; inspect current Runtime options
Local simulationYes, with a local primitive or simulatorYes, with a local primitive or simulatorGenerally requires a configured provider and service backend
Typical useSampling, classifiers, search circuits, distribution analysisVQE, QAOA objectives, Hamiltonian measurements, benchmarkingHardware 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.

  1. Build a circuit with measurements. A sampler does not infer the measurement you intended; add the appropriate classical registers and measurement operations.
  2. Select a local Sampler implementation for fast development, or a provider-backed Sampler for hardware execution.
  3. Submit one or more circuits with a shot count.
  4. 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.

  1. Prepare a circuit that creates the state of interest. Do not add final measurements solely for the Estimator workflow.
  2. Represent the observable with a supported operator format, such as a Pauli sum.
  3. Submit circuit-observable pairs, optionally with parameter values.
  4. 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:

  1. Install a compatible qiskit and qiskit-ibm-runtime combination.
  2. Authenticate and select a backend through QiskitRuntimeService.
  3. Construct SamplerV2 or EstimatorV2 with the current Runtime interface.
  4. Transpile circuits for the selected backend before submission when required by the workflow.
  5. Set supported shot, precision, batching, and resilience options deliberately rather than relying on defaults.
  6. 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:

  1. State whether the output you need is a distribution or an expectation value.
  2. Choose Sampler or Estimator accordingly, then select local or Runtime execution.
  3. Check the installed API and update imports and result parsing if necessary.
  4. Validate measurements, observables, parameter shapes, shots or precision, and batching.
  5. Transpile and inspect the circuit for the target backend.
  6. 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.

Related Topics

#Qiskit#Quantum Primitives#Estimator#Sampler#Qiskit Runtime
J

JustQubit Editorial Team

Quantum Computing Editor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.