Introduction to primitives

Why did Qiskit introduce primitives?

Similar to the early days of classical computers, when developers had to manipulate CPU registers directly, the early interface to QPUs simply returned the raw data from the control electronics. This was not a big issue when QPUs lived in labs and only allowed direct access by researchers. Acknowledging that most developers would not and should not be familiar with distilling such raw data into 0s and 1s, Qiskit introduced backend.run, a first abstraction for accessing QPUs in the cloud. This allowed developers to operate on a familiar data format and focus on the bigger picture.

As access to QPUs became more widespread, and with more quantum algorithms being developed, again the need for a higher-level abstraction emerged. In response, Qiskit introduced the primitives interface, which is optimized for two core tasks in quantum algorithm development: expectation value estimation (Estimator) and circuit sampling (Sampler). The goal is once again to help developers to focus more on innovation and less on data conversion. The primitives interface supersedes the backend.run interface, since Sampler provides the same direct hardware access that was offered by backend.run.

What is a primitive?

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 the field moves toward larger quantum processing units (QPUs) and more complex workflows, the focus shifts from interacting with individual qubit signals to viewing quantum devices as systems that perform necessary tasks.

The two most common tasks for quantum computers are sampling quantum states and calculating expectation values. These tasks motivated the design of the Qiskit primitives: Estimator and Sampler.

• Estimator computes expectation values of observables with respect to states prepared by quantum circuits.
• Sampler samples the output register from quantum circuit execution.

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.

Primitive definition and implementations

There are two types of Qiskit primitives: the base classes, and their implementations. The Qiskit primitives are defined by open-source primitive base classes that live in the Qiskit SDK (in the qiskit.primitives module). Providers (such as Qiskit Runtime) can use these base classes to derive their own Sampler and Estimator implementations. Most users will interact with provider implementations, not the base primitives.

Base classes

BaseEstimatorV2 and BaseSamplerV2 - Abstract base classes that define a common interface for implementing primitives. All other classes in the qiskit.primitives module inherit from these base classes. Developers should use these if they are interested in creating their own primitives-based execution model for a specific provider. These classes might also be useful for those who want to do highly customized processing and find that the existing primitives implementations are too simple for their needs. General users will not directly use the base classes.

Implementations

These are implementations of the primitives base classes:

• The Qiskit Runtime primitives (EstimatorV2 and SamplerV2) provide a more sophisticated implementation (for example, by including error mitigation) as a cloud-based service. This implementation of the base primitives is used to access IBM Quantum® hardware. They are accessed through IBM Qiskit Runtime.

• StatevectorEstimator and StatevectorSampler - Reference implementations of the primitives that use the simulator built into Qiskit. They are built with the Qiskit quantum_info module, producing results based on ideal statevector simulations. They are accessed through Qiskit.

• BackendEstimatorV2 and BackendSamplerV2 - You can use these classes to “wrap” any quantum computing resource into a primitive. This lets you 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. They are accessed by using Qiskit.

Benefits of Qiskit primitives

With primitives, Qiskit users can 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 take advantage of the latest advancements in error mitigation and suppression by toggling options such as the primitive's 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 such as advanced post-processing techniques. It is therefore easier for your users to benefit from your hardware's best capabilities.

Primitive details

As described previously, all primitives are created from the base classes; therefore, they have the same general structure and usage. For example, the format of the input for all Estimator primitives is the same. However, there are differences in implementations that make them unique.

Estimator

The Estimator primitive computes the expectation values for one or more 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. If the input contains measurements, they are ignored.

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.

The 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

The Sampler's core task is sampling the output register from the execution of one or more 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>, <one or more optional parameter value>, <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. Additionally, the input must contain measurements.

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),
])

Next steps