Tutorial: Running an Experiment#

See also

The complete source code of this tutorial can be found in

Running an Experiment.ipynb

The example dataset can be downloaded here.

This notebook presents a structure for setting up experiments using a combination of quantify-scheduler and quantify-core. quantify-scheduler provides a high-level interface with the hardware, allowing users to abstract hardware-specific nuances. quantify-core, on the other hand, serves as an experiment management tool, using quantify-scheduler as its hardware interface. This allows users to manage, execute, and analyze experiments easily.

The following is a general workflow for using Quantify

1. Initial Setup#

We first set up the directory in which all experimental data will be stored and managed.

from quantify_core.data import handling as dh
Data will be saved in:

Next, we need to initialize two classes: MeasurementControl for managing the experiment and InstrumentCoordinator for managing the control hardware.

from quantify_core.measurement.control import MeasurementControl
from quantify_scheduler.instrument_coordinator import InstrumentCoordinator

measurement_control = MeasurementControl("measurement_control")
instrument_coordinator = InstrumentCoordinator("instrument_coordinator")

2. Device Setup#

We set up the quantum device on which we perform the actual experiments. This one-qubit chip is represented by QuantumDevice where we add a single transmon qubit (represented by BasicTransmonElement) q0 to it.

# Device parameters
ACQ_DELAY = 100e-9
FREQ_01 = 4e9
from quantify_scheduler.device_under_test.quantum_device import QuantumDevice
from quantify_scheduler.device_under_test.transmon_element import BasicTransmonElement

single_qubit_device = QuantumDevice("single_qubit_device")

q0 = BasicTransmonElement("q0")

# Assign device parameters to transmon element

Quantum Devices and Elements

More information on quantum devices and elements can be found in Tutorial: Operations and Qubits.

3. Hardware Setup#

Let us now set up the connections to the control hardware. In this example, we use a dummy Qblox device that is created via an instance of the Cluster class, and is initialized with a dummy configuration consisting of a readout module in slot 1 and a control module in slot 2.

from qblox_instruments import Cluster, ClusterType
from quantify_scheduler.instrument_coordinator.components.qblox import ClusterComponent
cluster = Cluster(
        1: ClusterType.CLUSTER_QRM_RF,
        2: ClusterType.CLUSTER_QCM_RF,

ic_cluster = ClusterComponent(cluster)

The last part of setting up the hardware is to define the HardwareCompilationConfig and attach it to our single_qubit_device. The hardware compilation configuration is a pydantic datastructure, parsed either from a file or from a Python dictionary. It contains all of the information about the instruments used to run the experiment and is used to compile the schedule to hardware. For more information on this datastructure, please refer to the explanation in the User Guide.

hardware_comp_cfg = {
    "config_type": "quantify_scheduler.backends.qblox_backend.QbloxHardwareCompilationConfig",
    "hardware_description": {
        f"{cluster.name}": {
            "instrument_type": "Cluster",
            "ref": "internal",
            "modules": {
                "1": {
                    "instrument_type": "QRM_RF"
                "2": {
                    "instrument_type": "QCM_RF"
    "hardware_options": {
        "modulation_frequencies": {
            "q0:res-q0.ro": {"lo_freq": LO_FREQ_READOUT},
            "q0:mw-q0.01": {"lo_freq": LO_FREQ_QUBIT},
    "connectivity": {
        "graph": [
            (f"{cluster.name}.{cluster.module1.name.split('_')[-1]}.complex_output_0", "q0:res"),
            (f"{cluster.name}.{cluster.module2.name.split('_')[-1]}.complex_output_0", "q0:mw")
# Tie hardware config to device

4. Schedule Definition and Compilation#

Now we must create a schedule, where we define the set of operations that we wish to perform on the device under test. We define the schedule independent of the hardware configuration and rely on Quantify’s ability to compile a schedule to hardware for converting it to hardware-level commands. For this tutorial, we will define a simple schedule that will run a T1 experiment to determine the relaxation time of our qubit. For various delay times tau, we repeatedly excite the qubit, wait tau seconds and then measure the qubit.

from quantify_scheduler import Schedule
from quantify_scheduler.operations.gate_library import Measure, Reset, X

def t1_sched(times, repetitions=1):
    schedule = Schedule("T1", repetitions)
    for i, tau in enumerate(times):
        schedule.add(Reset("q0"), label=f"Reset {i}")
        schedule.add(X("q0"), label=f"pi {i}")
            Measure("q0", acq_index=i),
            label=f"Measurement {i}",
    return schedule

Pre-defined Schedules

The T1 schedule can be imported with from quantify_scheduler.schedules import t1_sched.

For more pre-defined schedules, see quantify_scheduler.schedules.

We can inspect the details of the schedule in three different ways: via (1) circuit and (2) pulse diagrams, or through (3) a timing table containing the timing and other information of each operation.

The plot_circuit_diagram() method can directly be used to display the quantum circuit that corresponds to the schedule that we defined above.

t1_schedule = t1_sched(times=[1e-6])

For displaying the pulse diagram and timing table, the schedule first needs to get timing information for each operation in the schedule. This is achieved by compiling the schedule using SerialCompiler. Please note that below in section 5. Experiment Execution and Analysis, the compilation is handled by MeasurementControl internally; it is done here only to enable displaying the timing table and pulse diagram.

Compiling to Hardware

More information on compilation can be found in Tutorial: Compiling to Hardware.

from quantify_scheduler.backends.graph_compilation import SerialCompiler

compiler = SerialCompiler(name="compiler", quantum_device=single_qubit_device)
compiled_schedule = compiler.compile(schedule=t1_schedule)

Each operation is compiled into pulses that can be viewed and inspected via the plot_pulse_diagram() method.