Tutorial 1. Controlling a basic experiment using MeasurementControl

See also

The complete source code of this tutorial can be found in

Tutorial 1. Controlling a basic experiment using MeasurementControl.ipynb

Introduction

Following this Tutorial requires familiarity with the core concepts of Quantify, we highly recommended to consult the (short) User guide before proceeding (see Quantify documentation). If you have some difficulties following the tutorial it might be worth reviewing the User guide !

This tutorial covers the basic usage of Quantify focusing on running basic experiments using MeasurementControl. The MeasurementControl is the main Instrument in charge of running any experiment.

It takes care of saving the data in a standardized format as well as live plotting of the data during the experiment. Quantify makes a distinction between Iterative measurements and Batched measurements.

In an Iterative measurement, the MeasurementControl processes each setpoint fully before advancing to the next.

In a Batched measurement, the MeasurementControl processes setpoints in batches, for example triggering 10 samples and then reading those 10 outputs. This is useful in resource constrained or overhead heavy situations.

Both measurement policies can be 1D, 2D or higher dimensional. Quantify also supports adaptive measurements in which the datapoints are determined during the measurement loop, which are explored in subsequent tutorials.

This tutorial is structured as follows. In the first section we use a 1D Iterative loop to explain the flow of a basic experiment. We start by setting up a noisy cosine model to serve as our mock setup and then use the meas_ctrl to measure this. We then execute an analysis on the data from this experiment.

Import modules and instantiate the MeasurementControl

import numpy as np

import quantify_core.visualization.pyqt_plotmon as pqm
from quantify_core.analysis import base_analysis as ba
from quantify_core.analysis import cosine_analysis as ca
from quantify_core.data.handling import (
    default_datadir,
    set_datadir,
)
from quantify_core.measurement import MeasurementControl
from quantify_core.utilities.examples_support import mk_cosine_instrument
from quantify_core.utilities.experiment_helpers import create_plotmon_from_historical

from quantify_core.utilities.inspect_utils import display_source_code
from quantify_core.visualization.instrument_monitor import InstrumentMonitor

Before instantiating any instruments or starting a measurement we change the directory in which the experiments are saved using the set_datadir() [get_datadir()] functions.

---

⚠️ Warning!

We recommend always setting the directory at the start of the python kernel and stick to a single common data directory for all notebooks/experiments within your measurement setup/PC.

The cell below sets a default data directory (~/quantify-data on Linux/macOS or $env:USERPROFILE\\quantify-data on Windows) for tutorial purposes. Change it to your desired data directory. The utilities to find/search/extract data only work if all the experiment containers are located within the same directory.

---

set_datadir(default_datadir())  # change me!

Data will be saved in:
C:\Users\AmirthaVarshinyArumu\quantify-data

meas_ctrl = MeasurementControl("meas_ctrl")

# Create the live plotting instrument which handles the graphical interface
# Two windows will be created, the main will feature 1D plots and any 2D plots will go to the secondary
plotmon = pqm.PlotMonitor_pyqt("plotmon")
# Connect the live plotting monitor to the measurement control
meas_ctrl.instr_plotmon(plotmon.name)

# The instrument monitor will give an overview of all parameters of all instruments
insmon = InstrumentMonitor("InstrumentMonitor")

QFontDatabase: Cannot find font directory C:/Users/AmirthaVarshinyArumu/miniforge3/lib/site-packages/PyQt5/Qt5/lib/fonts.
Note that Qt no longer ships fonts. Deploy some (from https://dejavu-fonts.github.io/ for example) or switch to fontconfig.
QFontDatabase: Cannot find font directory C:/Users/AmirthaVarshinyArumu/miniforge3/lib/site-packages/PyQt5/Qt5/lib/fonts.
Note that Qt no longer ships fonts. Deploy some (from https://dejavu-fonts.github.io/ for example) or switch to fontconfig.
QFontDatabase: Cannot find font directory C:/Users/AmirthaVarshinyArumu/miniforge3/lib/site-packages/PyQt5/Qt5/lib/fonts.
Note that Qt no longer ships fonts. Deploy some (from https://dejavu-fonts.github.io/ for example) or switch to fontconfig.
QFontDatabase: Cannot find font directory C:/Users/AmirthaVarshinyArumu/miniforge3/lib/site-packages/PyQt5/Qt5/lib/fonts.
Note that Qt no longer ships fonts. Deploy some (from https://dejavu-fonts.github.io/ for example) or switch to fontconfig.
QFontDatabase: Cannot find font directory C:/Users/AmirthaVarshinyArumu/miniforge3/lib/site-packages/PyQt5/Qt5/lib/fonts.
Note that Qt no longer ships fonts. Deploy some (from https://dejavu-fonts.github.io/ for example) or switch to fontconfig.

QFontDatabase: Cannot find font directory C:/Users/AmirthaVarshinyArumu/miniforge3/lib/site-packages/PyQt5/Qt5/lib/fonts.
Note that Qt no longer ships fonts. Deploy some (from https://dejavu-fonts.github.io/ for example) or switch to fontconfig.
QFontDatabase: Cannot find font directory C:/Users/AmirthaVarshinyArumu/miniforge3/lib/site-packages/PyQt5/Qt5/lib/fonts.
Note that Qt no longer ships fonts. Deploy some (from https://dejavu-fonts.github.io/ for example) or switch to fontconfig.
QFontDatabase: Cannot find font directory C:/Users/AmirthaVarshinyArumu/miniforge3/lib/site-packages/PyQt5/Qt5/lib/fonts.
Note that Qt no longer ships fonts. Deploy some (from https://dejavu-fonts.github.io/ for example) or switch to fontconfig.
QFontDatabase: Cannot find font directory C:/Users/AmirthaVarshinyArumu/miniforge3/lib/site-packages/PyQt5/Qt5/lib/fonts.
Note that Qt no longer ships fonts. Deploy some (from https://dejavu-fonts.github.io/ for example) or switch to fontconfig.
QFontDatabase: Cannot find font directory C:/Users/AmirthaVarshinyArumu/miniforge3/lib/site-packages/PyQt5/Qt5/lib/fonts.
Note that Qt no longer ships fonts. Deploy some (from https://dejavu-fonts.github.io/ for example) or switch to fontconfig.
QFontDatabase: Cannot find font directory C:/Users/AmirthaVarshinyArumu/miniforge3/lib/site-packages/PyQt5/Qt5/lib/fonts.
Note that Qt no longer ships fonts. Deploy some (from https://dejavu-fonts.github.io/ for example) or switch to fontconfig.
QFontDatabase: Cannot find font directory C:/Users/AmirthaVarshinyArumu/miniforge3/lib/site-packages/PyQt5/Qt5/lib/fonts.
Note that Qt no longer ships fonts. Deploy some (from https://dejavu-fonts.github.io/ for example) or switch to fontconfig.
QFontDatabase: Cannot find font directory C:/Users/AmirthaVarshinyArumu/miniforge3/lib/site-packages/PyQt5/Qt5/lib/fonts.
Note that Qt no longer ships fonts. Deploy some (from https://dejavu-fonts.github.io/ for example) or switch to fontconfig.
QFontDatabase: Cannot find font directory C:/Users/AmirthaVarshinyArumu/miniforge3/lib/site-packages/PyQt5/Qt5/lib/fonts.
Note that Qt no longer ships fonts. Deploy some (from https://dejavu-fonts.github.io/ for example) or switch to fontconfig.
QFontDatabase: Cannot find font directory C:/Users/AmirthaVarshinyArumu/miniforge3/lib/site-packages/PyQt5/Qt5/lib/fonts.
Note that Qt no longer ships fonts. Deploy some (from https://dejavu-fonts.github.io/ for example) or switch to fontconfig.

Define a simple model

We start by defining a simple model to mock our experiment setup (i.e. emulate physical setup for demonstration purposes). We will be generating a cosine with some normally distributed noise added on top of it.

# We create an instrument to contain all the parameters of our model to ensure
# we have proper data logging.
display_source_code(mk_cosine_instrument)

def mk_cosine_instrument() -> Instrument:
    """A container of parameters (mock instrument) providing a cosine model."""

    instr = Instrument("ParameterHolder")

    # ManualParameter's is a handy class that preserves the QCoDeS' Parameter
    # structure without necessarily having a connection to the physical world
    instr.add_parameter(
        "amp",
        initial_value=0.5,
        unit="V",
        label="Amplitude",
        parameter_class=ManualParameter,
    )
    instr.add_parameter(
        "freq",
        initial_value=1,
        unit="Hz",
        label="Frequency",
        parameter_class=ManualParameter,
    )
    instr.add_parameter(
        "t", initial_value=1, unit="s", label="Time", parameter_class=ManualParameter
    )
    instr.add_parameter(
        "phi",
        initial_value=0,
        unit="Rad",
        label="Phase",
        parameter_class=ManualParameter,
    )
    instr.add_parameter(
        "noise_level",
        initial_value=0.05,
        unit="V",
        label="Noise level",
        parameter_class=ManualParameter,
    )
    instr.add_parameter(
        "acq_delay", initial_value=0.02, unit="s", parameter_class=ManualParameter
    )

    def cosine_model():
        sleep(instr.acq_delay())  # simulates the acquisition delay of an instrument
        return (
            cos_func(instr.t(), instr.freq(), instr.amp(), phase=instr.phi(), offset=0)
            + np.random.randn() * instr.noise_level()
        )

    # Wrap our function in a Parameter to be able to associate metadata to it, e.g. unit
    instr.add_parameter(
        name="sig", label="Signal level", unit="V", get_cmd=cosine_model
    )

    return instr

pars = mk_cosine_instrument()

Many experiments involving physical instruments are much slower than the time it takes to simulate our cosine_model, that is why we added a sleep() controlled by the acq_delay.

This allows us to exemplify (later in the tutorial) some of the features of the meas_ctrl that would be imperceptible otherwise.

# by setting this to a non-zero value we can see the live plotting in action for a slower experiment
pars.acq_delay(0.0)

A 1D Iterative loop

Running the 1D experiment

The complete experiment is defined in just 4 lines of code. We specify what parameter we want to set, time t in this case, what points to measure at, and what parameter to measure. We then tell the MeasurementControl meas_ctrl to run which will return an Dataset object.

We use the Settable and Gettable helper classes to ensure our parameters contain the correct attributes.

meas_ctrl.settables(
    pars.t
)  # as a QCoDeS parameter, 't' obeys the JSON schema for a valid Settable and can be passed to the meas_ctrl directly.
meas_ctrl.setpoints(np.linspace(0, 2, 50))
meas_ctrl.gettables(
    pars.sig
)  # as a QCoDeS parameter, 'sig' obeys the JSON schema for a valid Gettable and can be passed to the meas_ctrl directly.
dataset = meas_ctrl.run("Cosine test")

Starting iterative measurement...

plotmon.main_QtPlot

QFontDatabase: Cannot find font directory C:/Users/AmirthaVarshinyArumu/miniforge3/lib/site-packages/PyQt5/Qt5/lib/fonts.
Note that Qt no longer ships fonts. Deploy some (from https://dejavu-fonts.github.io/ for example) or switch to fontconfig.
QFontDatabase: Cannot find font directory C:/Users/AmirthaVarshinyArumu/miniforge3/lib/site-packages/PyQt5/Qt5/lib/fonts.
Note that Qt no longer ships fonts. Deploy some (from https://dejavu-fonts.github.io/ for example) or switch to fontconfig.
QFontDatabase: Cannot find font directory C:/Users/AmirthaVarshinyArumu/miniforge3/lib/site-packages/PyQt5/Qt5/lib/fonts.
Note that Qt no longer ships fonts. Deploy some (from https://dejavu-fonts.github.io/ for example) or switch to fontconfig.
QFontDatabase: Cannot find font directory C:/Users/AmirthaVarshinyArumu/miniforge3/lib/site-packages/PyQt5/Qt5/lib/fonts.
Note that Qt no longer ships fonts. Deploy some (from https://dejavu-fonts.github.io/ for example) or switch to fontconfig.
QFontDatabase: Cannot find font directory C:/Users/AmirthaVarshinyArumu/miniforge3/lib/site-packages/PyQt5/Qt5/lib/fonts.
Note that Qt no longer ships fonts. Deploy some (from https://dejavu-fonts.github.io/ for example) or switch to fontconfig.

# The dataset has a time-based unique identifier automatically assigned to it
# The name of the experiment is stored as well
dataset.attrs["tuid"], dataset.attrs["name"]

('20240412-112803-004-55a0c3', 'Cosine test')

The dataset is stored as an xarray.Dataset (you can read more about xarray project at https://docs.xarray.dev/).

As shown below, a Data variable is assigned to each dimension of the settables and the gettable(s), following a format in which the settable takes the form x0, x1, etc. and the gettable(s) the form y0, y1, y2, etc.. You can click on the icons on the right to see the attributes of each variable and the values.

See Data storage in the User guide for details.

dataset

<xarray.Dataset> Size: 800B
Dimensions:  (dim_0: 50)
Coordinates:
    x0       (dim_0) float64 400B 0.0 0.04082 0.08163 0.1224 ... 1.918 1.959 2.0
Dimensions without coordinates: dim_0
Data variables:
    y0       (dim_0) float64 400B 0.5488 0.3882 0.4459 ... 0.4527 0.4895 0.5004
Attributes:
    tuid:                             20240412-112803-004-55a0c3
    name:                             Cosine test
    grid_2d:                          False
    grid_2d_uniformly_spaced:         False
    1d_2_settables_uniformly_spaced:  False

xarray.Dataset

• Dimensions:
  • dim_0: 50
• Coordinates: (1)
  • x0
    (dim_0)
    float64
    0.0 0.04082 0.08163 ... 1.959 2.0

    name :

    ParameterHolder.t

    long_name :

    ParameterHolder Time

    units :

    s

    batched :

    False

    array([0.        , 0.04081633, 0.08163265, 0.12244898, 0.16326531,
           0.20408163, 0.24489796, 0.28571429, 0.32653061, 0.36734694,
           0.40816327, 0.44897959, 0.48979592, 0.53061224, 0.57142857,
           0.6122449 , 0.65306122, 0.69387755, 0.73469388, 0.7755102 ,
           0.81632653, 0.85714286, 0.89795918, 0.93877551, 0.97959184,
           1.02040816, 1.06122449, 1.10204082, 1.14285714, 1.18367347,
           1.2244898 , 1.26530612, 1.30612245, 1.34693878, 1.3877551 ,
           1.42857143, 1.46938776, 1.51020408, 1.55102041, 1.59183673,
           1.63265306, 1.67346939, 1.71428571, 1.75510204, 1.79591837,
           1.83673469, 1.87755102, 1.91836735, 1.95918367, 2.        ])

• Data variables: (1)
  • y0
    (dim_0)
    float64
    0.5488 0.3882 ... 0.4895 0.5004

    name :

    sig

    long_name :

    Signal level

    units :

    V

    batched :

    False

    array([ 0.5487758 ,  0.38818358,  0.44591385,  0.30629198,  0.22527853,
            0.1450625 ,  0.07617889, -0.17562192, -0.21702234, -0.37907392,
           -0.45078379, -0.54770178, -0.57151835, -0.42382624, -0.39765829,
           -0.34478344, -0.21346116, -0.13985734, -0.01589218,  0.08943712,
            0.17102435,  0.27543444,  0.36200039,  0.43792348,  0.45795961,
            0.49441627,  0.45325334,  0.35007089,  0.36924123,  0.11782657,
            0.03601111, -0.02932342, -0.15192521, -0.26133845, -0.37872678,
           -0.45722892, -0.4324384 , -0.52408346, -0.46703305, -0.43336786,
           -0.39213345, -0.29364173, -0.14518903, -0.03090891,  0.09262532,
            0.1689748 ,  0.35398998,  0.45266731,  0.48951651,  0.50036978])

• Indexes: (0)
• Attributes: (5)

  tuid :

  20240412-112803-004-55a0c3

  name :

  Cosine test

  grid_2d :

  False

  grid_2d_uniformly_spaced :

  False

  1d_2_settables_uniformly_spaced :

  False

We can play with some live plotting options to see how the meas_ctrl behaves when changing the update interval.

# By default the meas_ctrl updates the datafile and live plot every 0.1 seconds (and not faster) to reduce overhead.
meas_ctrl.update_interval(
    0.1
)  # Setting it even to 0.01 creates a dramatic slowdown, try it out!

In order to avoid an experiment being bottlenecked by the update_interval we recommend setting it between ~0.1-1.0 s for a comfortable refresh rate and good performance.

meas_ctrl.settables(pars.t)
meas_ctrl.setpoints(np.linspace(0, 50, 1000))
meas_ctrl.gettables(pars.sig)
dataset = meas_ctrl.run("Many points live plot test")

Starting iterative measurement...

plotmon.main_QtPlot

pars.noise_level(0)  # let's disable noise from here on to get prettier figures

Analyzing the experiment

Plotting the data and saving the plots for a simple 1D case can be achieved in a few lines using a standard analysis from the quantify_core.analysis.base_analysis module. In the same module you can find several common analyses that might fit your needs. It also provides a base data-analysis class (BaseAnalysis) – a flexible framework for building custom analyses, which we explore in detail in a dedicated tutorial.

The Dataset generated by the meas_ctrl contains all the information required to perform basic analysis of the experiment. Running an analysis can be as simple as:

a_obj = ca.CosineAnalysis(label="Cosine test").run()
a_obj.display_figs_mpl()

Here the analysis loads the latest dataset on disk matching a search based on the label. See BaseAnalysis for alternative dataset specification.

After loading the data, it executes the different steps of the analysis and saves the results into a directory within the experiment container.

The Data storage contains more details on the folder structure and files contained in the data directory. The quantify_core.data.handling module provides convenience data searching and handling utilities like get_latest_tuid().

For guidance on creating custom analyses, e.g., fitting a model to the data, see Tutorial 3. Building custom analyses - the data analysis framework where we showcase the implementation of the analysis above.

A 2D Iterative loop

It is often desired to measure heatmaps (2D grids) of some parameter. This can be done by specifying two settables. The setpoints of the grid can be specified in two ways.

Method 1 - a quick grid

pars.acq_delay(0.0001)
meas_ctrl.update_interval(2.0)

times = np.linspace(0, 5, 129)
amps = np.linspace(-1, 1, 31)

meas_ctrl.settables([pars.t, pars.amp])
# meas_ctrl takes care of creating a meshgrid
meas_ctrl.setpoints_grid([times, amps])
meas_ctrl.gettables(pars.sig)
dataset = meas_ctrl.run("2D Cosine test")

Starting iterative measurement...

plotmon.secondary_QtPlot

a_obj = ba.Basic2DAnalysis(label="2D Cosine test").run()
a_obj.display_figs_mpl()

Method 2 - custom tuples in 2D

N.B. it is also possible to do this for higher dimensional loops

r = np.linspace(0, 1.2, 200)
dt = np.linspace(0, 0.5, 200)
f = 3
theta = np.cos(2 * np.pi * f * dt)


def polar_coords(r_, theta_):
    x_ = r_ * np.cos(2 * np.pi * theta_)
    y_ = r_ * np.sin(2 * np.pi * theta_)
    return x_, y_


x, y = polar_coords(r, theta)
setpoints = np.column_stack([x, y])
setpoints[:5]  # show a few points

array([[ 0.00000000e+00, -0.00000000e+00],
       [ 6.03000109e-03, -4.24843885e-05],
       [ 1.20555181e-02, -3.39642455e-04],
       [ 1.80542054e-02, -1.14460856e-03],
       [ 2.39683681e-02, -2.70570137e-03]])

pars.acq_delay(0.0001)
meas_ctrl.update_interval(2.0)

meas_ctrl.settables([pars.t, pars.amp])
meas_ctrl.setpoints(setpoints)
meas_ctrl.gettables(pars.sig)
dataset = meas_ctrl.run("2D radial setpoints")

Starting iterative measurement...

plotmon.secondary_QtPlot

In this case running a simple (non-interpolated) 2D analysis will not be meaningful. Nevertheless the dataset can be loaded back using the create_plotmon_from_historical()

plotmon_loaded = create_plotmon_from_historical(label="2D radial setpoints")
plotmon_loaded.secondary_QtPlot

QFontDatabase: Cannot find font directory C:/Users/AmirthaVarshinyArumu/miniforge3/lib/site-packages/PyQt5/Qt5/lib/fonts.
Note that Qt no longer ships fonts. Deploy some (from https://dejavu-fonts.github.io/ for example) or switch to fontconfig.
QFontDatabase: Cannot find font directory C:/Users/AmirthaVarshinyArumu/miniforge3/lib/site-packages/PyQt5/Qt5/lib/fonts.
Note that Qt no longer ships fonts. Deploy some (from https://dejavu-fonts.github.io/ for example) or switch to fontconfig.
QFontDatabase: Cannot find font directory C:/Users/AmirthaVarshinyArumu/miniforge3/lib/site-packages/PyQt5/Qt5/lib/fonts.
Note that Qt no longer ships fonts. Deploy some (from https://dejavu-fonts.github.io/ for example) or switch to fontconfig.
QFontDatabase: Cannot find font directory C:/Users/AmirthaVarshinyArumu/miniforge3/lib/site-packages/PyQt5/Qt5/lib/fonts.
Note that Qt no longer ships fonts. Deploy some (from https://dejavu-fonts.github.io/ for example) or switch to fontconfig.
QFontDatabase: Cannot find font directory C:/Users/AmirthaVarshinyArumu/miniforge3/lib/site-packages/PyQt5/Qt5/lib/fonts.
Note that Qt no longer ships fonts. Deploy some (from https://dejavu-fonts.github.io/ for example) or switch to fontconfig.
QFontDatabase: Cannot find font directory C:/Users/AmirthaVarshinyArumu/miniforge3/lib/site-packages/PyQt5/Qt5/lib/fonts.
Note that Qt no longer ships fonts. Deploy some (from https://dejavu-fonts.github.io/ for example) or switch to fontconfig.
QFontDatabase: Cannot find font directory C:/Users/AmirthaVarshinyArumu/miniforge3/lib/site-packages/PyQt5/Qt5/lib/fonts.
Note that Qt no longer ships fonts. Deploy some (from https://dejavu-fonts.github.io/ for example) or switch to fontconfig.
QFontDatabase: Cannot find font directory C:/Users/AmirthaVarshinyArumu/miniforge3/lib/site-packages/PyQt5/Qt5/lib/fonts.
Note that Qt no longer ships fonts. Deploy some (from https://dejavu-fonts.github.io/ for example) or switch to fontconfig.
QFontDatabase: Cannot find font directory C:/Users/AmirthaVarshinyArumu/miniforge3/lib/site-packages/PyQt5/Qt5/lib/fonts.
Note that Qt no longer ships fonts. Deploy some (from https://dejavu-fonts.github.io/ for example) or switch to fontconfig.
QFontDatabase: Cannot find font directory C:/Users/AmirthaVarshinyArumu/miniforge3/lib/site-packages/PyQt5/Qt5/lib/fonts.
Note that Qt no longer ships fonts. Deploy some (from https://dejavu-fonts.github.io/ for example) or switch to fontconfig.