Introduction to primitives
Computing systems are built on multiple layers of abstraction. Abstractions allow you to focus on a particular level of detail relevant to the task at hand. The closer you get to the hardware, the lower the level of abstraction you need (for example, you might want to manipulate electrical signals), and vice versa. The more complex the task you want to perform, the higher-level the abstractions will be (for example, you could be using a programming library to perform algebraic calculations).
In this context, a primitive is the smallest processing instruction, the simplest building block from which one can create something useful for a given abstraction level.
The recent progress in quantum computing has increased the need to work at higher levels of abstraction. As we move toward larger QPUs (quantum processing units) and more complex workflows, the focus shifts from interacting with individual qubit signals to viewing quantum devices as systems that perform tasks we need.
The two most common tasks quantum computers are used for are sampling quantum states and calculating expectation values. These tasks motivated the design of the Qiskit primitives: Sampler and Estimator.
In short, the computational model introduced by the Qiskit primitives moves quantum programming one step closer to where classical programming is today, where the focus is less on the hardware details and more on the results you are trying to achieve.
Implementation of Qiskit primitives
The Qiskit primitives are defined by open-source primitive base-classes, from
which different providers can derive their own Sampler and Estimator implementations. Among the implementations
using Qiskit, you can find reference primitive implementations for local simulation in the qiskit.primitives
module.
Providers like Qiskit Runtime enable access to appropriate QPUs through native implementations of
their own primitives.
Benefits of Qiskit primitives
For Qiskit users, primitives let you write quantum code for a specific QPU without having to explicitly
manage every detail. Also, because of the additional layer of abstraction, you might be able to more easily
access advanced hardware capabilities of a given provider. For example, with Qiskit Runtime primitives,
you can leverage the latest advancements in error mitigation and suppression by toggling options such as resilience_level
, rather than building your own implementation of these techniques.
For hardware providers, implementing primitives natively means you can provide your users with a more “out-of-the-box” way to access your hardware features. It is therefore easier for your users to benefit from your hardware's best capabilities.
Estimator
Estimator computes expectation values of observables with respect to states prepared by quantum circuits. The circuits can be parametrized, as long as the parameter values are also provided as input to the primitive.
The input is an array of PUBs. Each PUB is in the format (<single circuit>
, <one or more observables>
, <optional one or more parameter values>
, <optional precision>
), where the optional parameter values
can be a list or a single parameter. Different Estimator implementations support various configuration options.
The output is a PubResult
that contains the computed expectation values per pair, and their standard errors, in PubResult
form. Each PubResult
contains both data and metadata.
Estimator combines elements from observables and parameter values by following NumPy broadcasting rules as described in the Primitive inputs and outputs topic.
Example:
estimator.run([(circuit1, observable1, param_values1),(circuit2, observable2, param_values2)])
Sampler
Sampler's core task is sampling the output register from execution of quantum circuits. The input circuits can be parametrized, as long as the parameter values are also provided as input to the primitive.
The input is one or more PUBs, in the format (<single circuit>
, <optional one or more parameter values>
, <optional shots>
), where there can be multiple parameter values
items, and each item can be either an array or a single parameter, depending on the chosen circuit.
The output is counts or per-shot measurements, as PubResult
objects, without weights. The result class, however, has methods to return weighted samples, such as counts. See Primitive inputs and outputs for full details.
Example:
sampler.run([
(circuit1, param_values1, shots1),
(circuit2, param_values2, shots2),
])
How to use Qiskit primitives
The qiskit.primitives
module enables the development of primitive-style quantum programs and was specifically
designed to simplify switching between different types of quantum compute resources. The module provides three separate classes
for each primitive type:
StatevectorSampler
andStatevectorEstimator
These classes are reference implementations of both primitives and use the simulator built in to Qiskit. They leverage the Qiskit quantum_info
module in the background, producing results based on ideal statevector simulations.
BaseSampler
andBaseEstimator
These are abstract base classes that define a common interface for implementing primitives. All other classes in the qiskit.primitives
module inherit from these base classes, and developers should use these if they are interested in developing their own primitives-based execution model for a specific provider. These classes may also be useful for those who want to do highly customized processing and find the existing primitives implementations too simple for their needs.
BackendSampler
andBackendEstimator
If a provider does not support primitives natively, you can use these classes to “wrap” any quantum computing resource into a primitive. Users can write primitive-style code for providers that don’t yet have a primitives-based interface. These classes can be used just like the regular Sampler and Estimator, except they should be initialized with an additional backend
argument for selecting which quantum computer to run on.
The Qiskit Runtime primitives provide a more sophisticated implementation (for example, by including error mitigation) as a cloud-based service.
Next steps
- Read Get started with primitives to implement primitives in your work.
- Review detailed primitives examples.
- Practice with primitives by working through the Cost function lesson in IBM Quantum™ Learning.
- See the EstimatorV2 API reference and SamplerV2 API reference.
- Read Migrate to V2 primitives.