Skip to content

primitives.md

Latest commit

 

History

History
400 lines (301 loc) · 11.6 KB

primitives.md

File metadata and controls

400 lines (301 loc) · 11.6 KB
Raw

V2 Primitives and PUBs

Qiskit primitives standardize two core tasks:

  • Sampler executes measured circuits and returns shot-resolved classical data.
  • Estimator computes expectation values of observables for states prepared by circuits.

Use V2 interfaces. Their unit of work is a Primitive Unified Bloc (PUB).

Implementations

Implementation Use
StatevectorSampler Exact statevector evolution plus finite-shot sampling on the local CPU
StatevectorEstimator Local statevector expectation values
Aer SamplerV2 / EstimatorV2 High-performance and noisy local simulation
Runtime SamplerV2 / EstimatorV2 IBM QPUs and IBM Runtime services
BackendSamplerV2 / BackendEstimatorV2 Adapt a BackendV2 that lacks native primitives

The V2 run() structure is shared, but options are implementation-specific. Do not pass Runtime resilience options to statevector or Aer primitives.

Sampler PUBs

A Sampler PUB contains:

  1. One circuit with measurements.
  2. Optional parameter values.

Pass shots at the run() level unless a specific current API requires otherwise.

One Circuit

from qiskit import QuantumCircuit
from qiskit.primitives import StatevectorSampler

circuit = QuantumCircuit(2)
circuit.h(0)
circuit.cx(0, 1)
circuit.measure_all()

sampler = StatevectorSampler(seed=11)
primitive_result = sampler.run([circuit], shots=1024).result()
pub_result = primitive_result[0]

counts = pub_result.data.meas.get_counts()
bitstrings = pub_result.data.meas.get_bitstrings()
metadata = pub_result.metadata

meas is the name of the classical register created by measure_all().

Multiple Circuits

circuit_x = QuantumCircuit(1)
circuit_x.x(0)
circuit_x.measure_all()

circuit_h = QuantumCircuit(1)
circuit_h.h(0)
circuit_h.measure_all()

result = sampler.run([circuit_x, circuit_h], shots=512).result()
counts_x = result[0].data.meas.get_counts()
counts_h = result[1].data.meas.get_counts()

Each input PUB produces one PubResult.

Parameter Sweep

import numpy as np
from qiskit import QuantumCircuit
from qiskit.circuit import Parameter
from qiskit.primitives import StatevectorSampler

theta = Parameter("theta")
circuit = QuantumCircuit(1)
circuit.ry(theta, 0)
circuit.measure_all()

values = [[0.0], [np.pi / 2], [np.pi]]
sampler = StatevectorSampler(seed=11)
pub_result = sampler.run(
    [(circuit, values)],
    shots=256,
).result()[0]

for index, value in enumerate(values):
    counts = pub_result.data.meas.get_counts(index)
    print(value[0], counts)

For a shaped BitArray, pass an index to get_counts() when results must remain separated by parameter point. Calling it without an index can aggregate over axes.

Multiple Classical Registers

Sampler data fields use register names:

from qiskit import ClassicalRegister, QuantumCircuit, QuantumRegister
from qiskit.primitives import StatevectorSampler

qubits = QuantumRegister(2, "q")
left = ClassicalRegister(1, "left")
right = ClassicalRegister(1, "right")
circuit = QuantumCircuit(qubits, left, right)
circuit.h(qubits[0])
circuit.cx(qubits[0], qubits[1])
circuit.measure(qubits[0], left[0])
circuit.measure(qubits[1], right[0])

pub_result = StatevectorSampler(seed=11).run(
    [circuit],
    shots=256,
).result()[0]

left_counts = pub_result.data.left.get_counts()
right_counts = pub_result.data.right.get_counts()

Do not assume every result has .data.meas. Inspect circuit.cregs or pub_result.data.

Estimator PUBs

An Estimator PUB contains:

  1. One circuit, normally without final measurements.
  2. One observable or an array of observables.
  3. Optional parameter values.

One Circuit and Observable

from qiskit import QuantumCircuit
from qiskit.primitives import StatevectorEstimator
from qiskit.quantum_info import SparsePauliOp

circuit = QuantumCircuit(2)
circuit.h(0)
circuit.cx(0, 1)

observable = SparsePauliOp.from_list(
    [
        ("ZZ", 1.0),
        ("XX", 0.5),
    ]
)

estimator = StatevectorEstimator()
pub_result = estimator.run(
    [(circuit, observable)]
).result()[0]

expectation_values = pub_result.data.evs
standard_deviations = pub_result.data.stds

SparsePauliOp labels are little-endian with respect to qubit indices: the rightmost label character acts on qubit 0.

Parameter Sweep

import numpy as np
from qiskit import QuantumCircuit
from qiskit.circuit import Parameter
from qiskit.primitives import StatevectorEstimator
from qiskit.quantum_info import SparsePauliOp

theta = Parameter("theta")
circuit = QuantumCircuit(2)
circuit.ry(theta, 0)
circuit.cx(0, 1)

observable = SparsePauliOp.from_list([("ZI", 1.0), ("XX", 0.5)])
values = [[0.0], [np.pi / 4], [np.pi / 2]]

pub_result = StatevectorEstimator().run(
    [(circuit, observable, values)]
).result()[0]

print(pub_result.data.evs)

The final axis of values corresponds to list(circuit.parameters).

Multiple Observables

observables = [
    [SparsePauliOp.from_list([("ZZ", 1.0)])],
    [SparsePauliOp.from_list([("XX", 1.0)])],
]

pub_result = StatevectorEstimator().run(
    [(circuit, observables, values)]
).result()[0]
assert pub_result.data.evs.shape == (2, len(values))

Estimator V2 broadcasts observable and parameter arrays. For nontrivial shapes, build a small test first and assert the output shape rather than relying on intuition.

Precision and Shots

  • Sampler controls finite sampling with shots.
  • Estimator controls target accuracy with precision.
  • StatevectorEstimator is exact at its default precision of zero for supported circuits and Pauli observables.
  • Runtime may translate requested precision into a shot and randomization budget.
  • Runtime twirling settings can affect how shots are allocated.
pub_result = runtime_estimator.run(
    [(isa_circuit, isa_observable)],
    precision=0.02,
).result()[0]

Record requested precision, realized metadata, primitive options, and usage. Do not compare two experiments solely by nominal shot count when mitigation or twirling differs.

Runtime Sampler V2

Runtime circuits must already satisfy the selected backend's ISA:

from qiskit import QuantumCircuit
from qiskit.transpiler import generate_preset_pass_manager
from qiskit_ibm_runtime import QiskitRuntimeService, SamplerV2 as Sampler

service = QiskitRuntimeService()
backend = service.least_busy(
    operational=True,
    simulator=False,
    min_num_qubits=2,
)

circuit = QuantumCircuit(2)
circuit.h(0)
circuit.cx(0, 1)
circuit.measure_all()

pass_manager = generate_preset_pass_manager(
    backend=backend,
    optimization_level=1,
    seed_transpiler=11,
)
isa_circuit = pass_manager.run(circuit)

sampler = Sampler(
    mode=backend,
    options={"default_shots": 1024},
)
job = sampler.run([isa_circuit])
print(job.job_id())
counts = job.result()[0].data.meas.get_counts()

Sampler noise-management options include dynamical decoupling, twirling, execution, environment, and simulator settings. Sampler does not expose Estimator resilience levels.

Runtime Estimator V2

Map observables through the final circuit layout:

from qiskit.quantum_info import SparsePauliOp
from qiskit_ibm_runtime import EstimatorV2 as Estimator

observable = SparsePauliOp.from_list([("ZZ", 1.0)])
isa_observable = observable.apply_layout(isa_circuit.layout)

estimator = Estimator(
    mode=backend,
    options={"resilience_level": 1},
)
job = estimator.run(
    [(isa_circuit, isa_observable)],
    precision=0.02,
)
print(job.job_id())
pub_result = job.result()[0]
print(pub_result.data.evs, pub_result.data.stds)

For a parameterized circuit, transpile once and include values in the PUB:

pub = (isa_circuit, isa_observable, parameter_values)
pub_result = estimator.run([pub], precision=0.02).result()[0]

Runtime Options

Set options with a dictionary, an options dataclass, direct attributes, or .update():

from qiskit_ibm_runtime import EstimatorOptions, EstimatorV2 as Estimator

options = EstimatorOptions(
    resilience_level=2,
    resilience={
        "zne_mitigation": True,
        "zne": {"noise_factors": [1, 3, 5]},
    },
)
estimator = Estimator(mode=backend, options=options)

estimator.options.default_precision = 0.02
estimator.options.update(
    dynamical_decoupling={
        "enable": True,
        "sequence_type": "XpXm",
    }
)

Current Estimator resilience levels are 0, 1, and 2; there is no level 3. Advanced features can be incompatible with each other, especially fractional gates, gate twirling, PEA, PEC, and gate-folding ZNE. Consult the current options guide before combining them.

Do not use the old shared Options() object or .set_options().

Job, Batch, and Session Modes

from qiskit_ibm_runtime import (
    Batch,
    EstimatorV2 as Estimator,
    SamplerV2 as Sampler,
    Session,
)

# Job mode
sampler = Sampler(mode=backend)
job = sampler.run([isa_circuit], shots=1024)

# Batch mode: independent jobs
with Batch(backend=backend, max_time="10m") as batch:
    sampler = Sampler(mode=batch)
    batch_jobs = [
        sampler.run([circuit], shots=1024)
        for circuit in isa_circuits
    ]

# Session mode: iterative jobs; unavailable on the Open Plan
with Session(backend=backend, max_time="20m") as session:
    estimator = Estimator(mode=session)
    session_jobs = [
        estimator.run([pub], precision=0.03)
        for pub in iterative_pubs
    ]

Create the primitive with mode=batch or mode=session. Passing the backend instead runs in job mode even inside a context.

Adapting a Backend

Use backend primitives when a provider exposes BackendV2 but no native V2 primitive:

from qiskit.primitives import BackendEstimatorV2, BackendSamplerV2

sampler = BackendSamplerV2(backend=backend)
estimator = BackendEstimatorV2(backend=backend)

Provider behavior, result quality, and options differ. Transpile for the backend target and read the provider documentation.

Result Handling Checklist

For every result:

  1. Match each PubResult to its input PUB.
  2. Use the actual classical-register field for Sampler output.
  3. Preserve array dimensions for parameter and observable sweeps.
  4. Store metadata alongside values or counts.
  5. Store the job ID before blocking on result().
  6. Record package versions, backend name, seeds, precision or shots, and all non-default options.
  7. Treat mitigated expectation values as estimates with method-dependent bias and overhead.

Migration Traps

Old pattern Current pattern
Sampler() or Estimator() V1 Explicit V2 implementation
.quasi_dists Shot-resolved BitArray, such as .data.meas.get_counts()
.values .result()[i].data.evs
Parallel circuit/observable/value lists One or more PUB tuples
Shared Options() SamplerOptions, EstimatorOptions, dictionaries, or .options.update()
backend= / session= primitive arguments mode=
Runtime auto-transpilation Explicit ISA circuit preparation
Unmapped observables observable.apply_layout(isa_circuit.layout)

Common Errors

  • No meas field: the circuit has a differently named register or no measurements.
  • Shape/broadcast error: check circuit.parameters, the last parameter-value axis, and observable-array shape.
  • Circuit not ISA-compatible: transpile against the exact backend target before Runtime execution.
  • Observable qubit mismatch: apply the circuit layout and confirm the resulting width.
  • Unsupported option: options are implementation- and version-specific.
  • Session rejected: Open Plan workloads must use job or batch mode.
  • Unexpected cost: mitigation, twirling, and precision settings can multiply circuit and shot counts.