Acquisition framework#


In this reference guide, we provide a detailed description of the acquisition framework. Specifically, the problem the acquisition framework intends to solve is that of specifying how acquired signals should be processed, and where the resulting data should be stored. A user should be able to relate individual entries in a dataset to the different acquisitions specified in a schedule.


Fig. 7 A schematic overview of the different abstraction layers and the compilation process.#

To explain how these concepts work together, we start by defining several concepts.

Definitions and specifications#


This section defines the concepts that are relevant to understand the acquisition framework. Take note that not all concepts have an implementation as a class in the code. If an implementation as a python class exists within quantify, a reference will be provided here.

Although, in the ideal case the (definition of) the concept, and the implementation are identical, there might be differences between the definitions provided here and the implementation in the code. E.g., the implementation might be incomplete, or more limited in scope. Should you find a case where the two directly contradict each other, this is considered a defect and we kindly ask you to fill an issue to report the defect.


In quantify, a Measurement at the quantum-circuit layer can be expressed as an Acquisition at the quantum-device layer.

When representing a Measure at the quantum-circuit layer, the default behavior is that the AcquisitionChannel, and AcquisitionProtocol are taken from the DeviceCompilationConfig, and the AcquisitionIndex is determined automatically. However, a user may want to specify these parameters manually and thereby overwrite the defaults that are specified in the DeviceCompilationConfig.

Hide code cell source
from quantify_scheduler import Schedule
from quantify_scheduler.operations.gate_library import Measure

schedule = Schedule("Measurement")

_ = schedule.plot_circuit_diagram()



An Acquisition is an Operation that can be added to a Schedule that must consist of (at least) an AcquisitionProtocol specifying how the acquired signal is to be processed, and an AcquisitionChannel and AcquisitionIndex specifying where the acquired data is to be stored in the RawDataset.


An Experiment is a procedure carried out under controlled conditions in order to make a discovery, test a hypothesis, or demonstrate a known fact.


An ExperimentDescription is a description of the procedure that is carried out in an Experiment. A valid ExperimentDescription can consist of Settable(s), Gettable(s), instructions to determine the Setpoints, and predefined DataProcessing step(s).


A Dataset is structured data with metadata (e.g., an Xarray dataset). Within the quantify framework we like to associate specific metadata to a dataset. This is specified in the dataset design.


A RawDataset is a valid Dataset. The structure of a RawDataset is defined by what is returned by the Hardware Abstraction Layer upon execution of a Schedule. Note that this implies that this format is backend independent. Data entries in the RawDataset are labeled by an AcquisitionChannel, and an AcquisitionIndex.

The structure of a RawDataset (shape, type and units of the data) should be predictable before executing a Schedule.


A ProcessedDataset is a valid Dataset. The structure is defined by the Experiment that is performed and is described by the DataProcessing step of the ExperimentDescription.


DataProcessing: A predefined procedure of operations that can be performed on a Dataset to return another Dataset (which may also include figures or quantities of interest).


An AcquisitionProtocol describes how to process an acquired signal. Each acquisition protocol should have a corresponding data schema defined and documented that specifies the type, shape, and units, of the data that performing the protocol will return. The reference guide on acquisition protocols provides an overview of different acquisition protocols included in quantify.


An AcquisitionChannel is a stream of data that corresponds to a device element that is measured sequentially in a specified regime (i.e., using the specified AcquisitionProtocol). Each acquisition channel must have a name; a str or int that is used to refer to the acquisition channel (within e.g., operations, schedules and datasets), and an optional long_name that serves as a human-readable variant of the name and can be associated to RawDataset. As a consequence of these definitions, all Acquisitions associated to an AcquisitionChannel must have the same AcquisitionProtocol and BinMode.

An AcquisitionChannel commonly corresponds to a qubit but also makes sense in isolation (e.g., when performing spectroscopy). A qubit can in principle have multiple acquisition channels associated with it.

In the resulting RawDataset data from each acquisition channel will be formatted as a separate data array. The exact shape and structure of the data is determined by the AcquisitionProtocol and BinMode


An AcquisitionIndex is an identifier of an acquisition within a single repetition of a schedule, unique per acquisition channel (i.e., an index value occurs only once per AcquisitionChannel).

In the resulting RawDataset, the acquisition index corresponds to a data array dimension and determines the order in which data appears in the data array for each acquisition channel.


AcquisitionCoordinates are an additional piece of information associated with an acquisition, provided by a user during the schedule construction.

In a RawDataset coordinates correspond to xarray coordinates along the AcquistionIndex dimension of the acquisition channel data arrays. Coordinates provided by a user are formatted as a data array using numpy conventions, thus, for performance reasons they should have uniform data type that can be handled with numpy. AcquisitionCoordinates can optionally have units and long_name attributes associated with it.

Bin mode#

A BinMode is a property of an acquisition channel that describes how to handle multiple schedule repetitions of the same Acquisition operation. The most common use-case for this is when iterating over multiple repetitions of a Schedule When the bin_mode is set to APPEND new entries will be added as a list along the repetitions dimension.

Common BinModes are APPEND and AVERAGE, which will append entries along the “repetition” dimension or average all repetitions for the schedule.