User guide¶

Introduction¶

A quantify_core experiment typically consists of a data-acquisition loop in which one or more parameters are set and one or more parameters are measured.

The core of Quantify can be understood by understanding the following concepts:

Instruments and Parameters
Measurement Control
Settables and Gettables
Data storage
Analysis

Code snippets¶

Instruments and Parameters¶

Parameter¶

A parameter represents a state variable of the system.

A parameter can be get and/or set able.

Contains metadata such as units and labels.

Commonly implemented using the QCoDeS Parameter class.

A parameter implemented using the QCoDeS Parameter class is a valid Settable and Gettable and as such can be used directly in an experiment loop in the [Measurement Control]. (see subsequent sections)

Instrument¶

An Instrument is a container for parameters that typically (but not necessarily) corresponds to a physical piece of hardware.

Instruments provide the following functionality.

Container for parameters.
A standardized interface.
Provide logging of parameters through the snapshot() method.
All instruments inherit from the QCoDeS Instrument class.
Are shown by default in the InstrumentMonitor

Measurement Control¶

The MeasurementControl (meas_ctrl) is in charge of the data-acquisition loop and is based on the notion that, in general, an experiment consists of the following three steps:

Initialize (set) some parameter(s),
Measure (get) some parameter(s),
Store the data.

Quantify provides two helper classes, Settable and Gettable to aid in these steps, which are explored further in later sections of this article.

MeasurementControl provides the following functionality

Enforce standardization of experiments
Standardized data storage
Live plotting of the experiment
n-dimensional sweeps
Data acquisition controlled iteratively or in batches
Adaptive sweeps (measurement points are not predetermined at the beginning of an experiment)

Basic example, a 1D iterative measurement loop¶

Running an experiment is simple! Simply define what parameters to set, and get, and what points to loop over.

In the example below we want to set frequencies on a microwave source and acquire the signal from the pulsar readout module.

meas_ctrl.settables(
    mw_source1.freq
)  # We want to set the frequency of a microwave source
meas_ctrl.setpoints(np.arange(5e9, 5.2e9, 100e3))  # Scan around 5.1 GHz
meas_ctrl.gettables(pulsar_QRM.signal)  # acquire the signal from the pulsar QRM
dset = meas_ctrl.run(name="Frequency sweep")  # run the experiment

Starting iterative measurement...

100% completed | elapsed time:      0s | time left:      0s  

100% completed | elapsed time:      0s | time left:      0s  

The MeasurementControl can also be used to perform more advanced experiments such as 2D scans, pulse-sequences where the hardware is in control of the acquisition loop, or adaptive experiments in which it is not known what data points to acquire in advance, they are determined dynamically during the experiment. Take a look at some of the tutorial notebooks for more in-depth examples on usage and application.

Control Mode¶

Batched mode can be used to deal with constraints imposed by (hardware) resources or to reduce overhead.

In Iterative mode, the meas_ctrl steps through each setpoint one at a time, processing them one by one.

In Batched mode, the meas_ctrl vectorizes the setpoints such that they are processed in batches. The size of these batches is automatically calculated but usually dependent on resource constraints; you may have a device which can hold 100 samples but you wish to sweep over 2000 points.

Note

The maximum batch size of the settable(s)/gettable(s) should be specified using the .batch_size attribute. If not specified infinite size is assumed and all setpoint are passed to the settable(s).

Tip

In Batched mode it is still possible to perform outer iterative sweeps with an inner batched sweep. This is performed automatically when batched settables (.batched=True) are mixed with iterative settables (.batched=False). To correctly grid the points in this mode use MeasurementControl.setpoints_grid().

Control mode is detected automatically based on the .batched attribute of the settable(s) and gettable(s); this is expanded upon in subsequent sections.

Note

All gettables must have the same value for the .batched attribute. Only when all gettables have .batched=True, settables are allowed to have mixed .batched attribute (e.g. settable_A.batched=True, settable_B.batched=False).

Settables and Gettables¶

Experiments typically involve varying some parameters and reading others. In Quantify we encapsulate these concepts as the Settable and Gettable respectively. As their name implies, a Settable is a parameter you set values to, and a Gettable is a parameter you get values from.

The interfaces for Settable and Gettable parameters are encapsulated in the Settable and Gettable helper classes respectively. We set values to Settables; these values populate an X-axis. Similarly, we get values from Gettables which populate a Y-axis. These classes define a set of mandatory and optional attributes the MeasurementControl recognizes and will use as part of the experiment, which are expanded up in the API Reference. For ease of use, we do not require users to inherit from a Gettable/Settable class, and instead provide contracts in the form of JSON schemas to which these classes must fit (see Settable and Gettable docs for these schemas). In addition to using a library which fits these contracts (such as the Parameter family of classes) we can define our own Settables and Gettables.

t = ManualParameter("time", label="Time", unit="s")


class WaveGettable:
    """An examples of a gettable."""

    def __init__(self):
        self.unit = "V"
        self.label = "Amplitude"
        self.name = "sine"

    def get(self):
        """Return the gettable value."""
        return np.sin(t() / np.pi)

    def prepare(self) -> None:
        """Optional methods to prepare can be left undefined."""
        print("Preparing the WaveGettable for acquisition.")

    def finish(self) -> None:
        """Optional methods to finish can be left undefined."""
        print("Finishing WaveGettable to wrap up the experiment.")


# verify compliance with the Gettable format
wave_gettable = WaveGettable()
Gettable(wave_gettable)

<__main__.WaveGettable at 0x7f41481aacd0>

Note: “Grouped” gettable(s) are also allowed.

Below we create a Gettable which returns two distinct quantities at once:

t = ManualParameter(
    "time",
    label="Time",
    unit="s",
    vals=validators.Numbers(),  # accepts a single number, e.g. a float or integer
)


class DualWave1D:
    """Example of a "dual" gettable."""

    def __init__(self):
        self.unit = ["V", "V"]
        self.label = ["Sine Amplitude", "Cosine Amplitude"]
        self.name = ["sin", "cos"]

    def get(self):
        """Return the value of the gettable."""
        return np.array([np.sin(t() / np.pi), np.cos(t() / np.pi)])

    # N.B. the optional prepare and finish methods are omitted in this Gettable.


# verify compliance with the Gettable format
wave_gettable = DualWave1D()
Gettable(wave_gettable)

<__main__.DualWave1D at 0x7f41481aa310>

Depending on which Control Mode the MeasurementControl is running in, the interfaces for Settables (their input interface) and Gettables (their output interface) are slightly different.

Note

It is also possible for batched Gettables return an array with length less than then the length of the setpoints, and similarly for the input of the Settables. This is often the case when working with resource constrained devices, for example if you have n setpoints but your device can load only less than n datapoints into memory. In this scenario, the meas_ctrl tracks how many datapoints were actually processed, automatically adjusting the size of the next batch.

Example

time = ManualParameter(
    name="time",
    label="Time",
    unit="s",
    vals=validators.Arrays(),  # accepts an array of values
)
signal = Parameter(
    name="sig_a", label="Signal", unit="V", get_cmd=lambda: np.cos(time())
)

time.batched = True
time.batch_size = 5
signal.batched = True
signal.batch_size = 10

meas_ctrl.settables(time)
meas_ctrl.gettables(signal)
meas_ctrl.setpoints(np.linspace(0, 7, 23))
dset = meas_ctrl.run("my experiment")
dset_grid = dh.to_gridded_dataset(dset)

dset_grid.y0.plot()

Starting batched measurement...
Iterative settable(s) [outer loop(s)]:
	 --- (None) --- 
Batched settable(s):
	 time 
Batch size limit: 5


100% completed | elapsed time:      0s | time left:      0s  last batch size:      3  

100% completed | elapsed time:      0s | time left:      0s  last batch size:      3  

[<matplotlib.lines.Line2D at 0x7f410f693730>]

.batched and .batch_size¶

The Gettable and Settable objects can have a bool property .batched (defaults to False if not present); and a int property .batch_size.

Setting the .batched property to True enables the batch Control Mode in the MeasurementControl. In this mode, if present, the .batch_size attribute is used to determine the maximum size of a batch of setpoints.

Heterogeneous batch size and effective batch size

The minimum .batch_size among all settables and gettables will determine the (maximum) size of a batch. During execution of a measurement the size of a batch will be reduced if necessary to comply to the setpoints grid and/or total number of setpoints.

.prepare() and .finish()¶

Optionally the .prepare() and .finish() can be added. These methods can be used to setup and teardown work. For example, arming a piece of hardware with data and then closing a connection upon completion.

The .finish() runs once at the end of an experiment.

For settables, .prepare() runs once before the start of a measurement.

For batched gettables, .prepare() runs before the measurement of each batch. For iterative gettables, the .prepare() runs before each loop counting towards soft-averages [controlled by meas_ctrl.soft_avg() which resets to 1 at the end of each experiment].

Analysis¶

To aid with data analysis, quantify comes with an analysis module containing a base data-analysis class (BaseAnalysis) that is intended to serve as a template for analysis scripts and several standard analyses such as the BasicAnalysis, the Basic2DAnalysis and the ResonatorSpectroscopyAnalysis.

The idea behind the analysis class is that most analyses follow a common structure consisting of steps such as data extraction, data processing, fitting to some model, creating figures, and saving the analysis results.

To showcase the analysis usage we generates a dataset that we would like to analyze.

Generate a dataset labeled “Cosine experiment”

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()
meas_ctrl.settables(pars.t)
meas_ctrl.setpoints(np.linspace(0, 2, 50))
meas_ctrl.gettables(pars.sig)
dataset = meas_ctrl.run("Cosine experiment")
dataset

Starting iterative measurement...

  2% completed | elapsed time:      0s | time left:      1s  
  2% completed | elapsed time:      0s | time left:      1s  

 52% completed | elapsed time:      0s | time left:      0s  
 52% completed | elapsed time:      0s | time left:      0s  

100% completed | elapsed time:      1s | time left:      0s  

100% completed | elapsed time:      1s | time left:      0s  

<xarray.Dataset>
Dimensions:  (dim_0: 50)
Coordinates:
    x0       (dim_0) float64 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 0.4427 0.4202 0.4573 0.2919 ... 0.4737 0.3959 0.528
Attributes:
    tuid:                             20230926-194519-516-fe8f1e
    name:                             Cosine experiment
    grid_2d:                          False
    grid_2d_uniformly_spaced:         False
    1d_2_settables_uniformly_spaced:  False

Using an analysis class¶

Running an analysis is very simple:

a_obj = ca.CosineAnalysis(label="Cosine experiment")
a_obj.run()  # execute the analysis.
a_obj.display_figs_mpl()  # displays the figures created in previous step.

The analysis was executed against the last dataset that has the label "Cosine experiment" in the filename.

After the analysis the experiment container will look similar to the following:

experiment_container_path = dh.locate_experiment_container(tuid=dataset.tuid)
print(display_tree(experiment_container_path, string_rep=True), end="")

20230926-194519-516-fe8f1e-Cosine experiment/
├── analysis_CosineAnalysis/
│   ├── dataset_processed.hdf5
│   ├── figs_mpl/
│   │   ├── cos_fit.png
│   │   └── cos_fit.svg
│   ├── fit_results/
│   │   └── cosine.txt
│   └── quantities_of_interest.json
├── dataset.hdf5
└── snapshot.json

The analysis object contains several useful methods and attributes such as the quantities_of_interest, intended to store relevant quantities extracted during analysis, and the processed dataset.

# for example, the fitted frequency and amplitude are stored
freq = a_obj.quantities_of_interest["frequency"]
amp = a_obj.quantities_of_interest["amplitude"]
print(f"frequency {freq}")
print(f"amplitude {amp}")

frequency 1.001+/-0.006
amplitude 0.492+/-0.010

The use of these methods and attributes is described in more detail in Tutorial 3. Building custom analyses - the data analysis framework.

Creating a custom analysis class¶

The analysis steps and their order of execution is determined by the analysis_steps attribute as an Enum (AnalysisSteps). The corresponding steps are implemented as methods of the analysis class. An analysis class inheriting from the abstract-base-class (BaseAnalysis) will only have to implement those methods that are unique to the custom analysis. Additionally, if required, a customized analysis flow can be specified by assigning it to the analysis_steps attribute.

The simplest example of an analysis class is the BasicAnalysis that only implements the create_figures() method and relies on the base class for data extraction and saving of the figures.

Take a look at the source code (also available in the API reference):

BasicAnalysis source code

display_source_code(ba.BasicAnalysis)

class BasicAnalysis(BaseAnalysis):
    """
    A basic analysis that extracts the data from the latest file matching the label
    and plots and stores the data in the experiment container.
    """

    def create_figures(self):
        """
        Creates a line plot x vs y for every data variable yi and coordinate xi in the
        dataset.
        """

        # NB we do not use `to_gridded_dataset` because that can potentially drop
        # repeated measurement of the same x0_i setpoint (e.g., AllXY experiment)
        dataset = self.dataset
        # for compatibility with older datasets
        # in case "x0" is not a coordinate we use "dim_0"
        coords = list(dataset.coords)
        dims = list(dataset.dims)
        plot_against = coords if coords else (dims if dims else [None])
        for idx, xi in enumerate(plot_against):
            for yi, yvals in dataset.data_vars.items():
                # for compatibility with older datasets, do not plot "x0" vs "x0"
                if yi.startswith("y"):
                    fig, ax = plt.subplots()

                    fig_id = f"Line plot x{idx}-{yi}"

                    yvals.plot.line(ax=ax, x=xi, marker=".")

                    adjust_axeslabels_SI(ax)

                    qpl.set_suptitle_from_dataset(fig, self.dataset, f"x{idx}-{yi}")

                    # add the figure and axis to the dicts for saving
                    self.figs_mpl[fig_id] = fig
                    self.axs_mpl[fig_id] = ax

A slightly more complex use case is the ResonatorSpectroscopyAnalysis that implements process_data() to cast the data to a complex-valued array, run_fitting() where a fit is performed using a model (from the quantify_core.analysis.fitting_models library), and create_figures() where the data and the fitted curve are plotted together.

Creating a custom analysis for a particular type of dataset is showcased in the Tutorial 3. Building custom analyses - the data analysis framework. There you will also learn some other capabilities of the analysis and practical productivity tips.

User guide¶

Introduction¶

Code snippets¶

Instruments and Parameters¶

Parameter¶

Instrument¶

Measurement Control¶

Basic example, a 1D iterative measurement loop¶

Control Mode¶

Settables and Gettables¶

.batched and .batch_size¶

.prepare() and .finish()¶

Data storage¶

Data Directory¶

Experiment Container¶

Dataset¶

Associating dimensions to coordinates¶

Snapshot¶

Analysis¶

Using an analysis class¶

Creating a custom analysis class¶

Examples: Settables and Gettables¶

Iterative control mode¶

Single-float-valued settable(s) and gettable(s)¶

Single-float-valued settable(s) with multiple float-valued gettable(s)¶

Batched control mode¶

Float-valued array settable(s) and gettable(s)¶

Float-valued array settable(s) with multi-return float-valued array gettable(s)¶