See also

A Jupyter notebook version of this tutorial can be downloaded here.

Basic sequencing#


A version of this tutorial suitable for RF modules can be found here.

In this tutorial we will demonstrate basic sequencer based operations (see Sequencer Operation) for programming a qblox instrument. This includes creating a sequence consisting of waveforms and a simple Q1ASM program, and executing this sequence synchronously on multiple sequencers.

The general process for setting up and executing a program on a Q1 sequencer is as follows:

  1. Connect to instrument

  2. Prepare a sequence (JSON formatted file) which consists of

    • Waveforms for playback

    • Weights for weighted integration

    • Acquisitions for capture

    • Q1ASM program to be executed by the sequencer

  3. This sequence is then loaded onto a sequencer on the connected instrument using the method instrument_variable.sequencerX.sequence("SequenceFile.json")

  4. The sequencer is then setup over its API as necessary

  5. Sequencer is then armed and started to commence the experiment

  6. Stop the sequencer and close down all instruments

This tutorial will give a basic introduction on how to work with the waveforms and Q1ASM segments of a sequence.

In the Tutorial the sequence is going to consecutively play two waveforms, a gaussian and block with a duration of 20ns each, with an increasing wait period in between them. We will increase the wait period by 20ns repeated 100 times, after which the sequence is stopped. The sequence will also trigger marker output 1 at every interval, so that the sequence can be easily monitored on an oscilloscope.

We can perform this tutorial with either a Cluster QCM/QRM . We use the term ‘QxM’ encompassing both QCM and QRM modules.

To run this tutorial please make sure you have installed and enabled ipywidgets:

pip install ipywidgets
jupyter nbextension enable --py widgetsnbextension


First, we are going to import the required packages.

# Import ipython widgets
import contextlib
import json

import ipywidgets as widgets
import matplotlib.pyplot as plt
import numpy as np

# Set up the environment.
import scipy.signal
from IPython.display import display
from qcodes import Instrument

from qblox_instruments import Cluster, PlugAndPlay

Scan For Clusters#

We scan for the available devices connected via ethernet using the Plug & Play functionality of the Qblox Instruments package (see Plug & Play for more info).

!qblox-pnp list
 - cluster_mm 0.6.1 with name "QAE_1" and serial number 00015_2320_004
 - cluster_mm 0.6.1 with name "cluster-mm" and serial number 00015_2219_003
 - pulsar_qcm 0.11.1 with name "pulsar-qcm" and serial number 00012_2039_005
 - pulsar_qrm 0.11.1 with name "pulsar-qrm" and serial number 00013_2120_008
 - cluster_mm 0.6.1 with name "cluster-mm" and serial number 00015_2320_003
cluster_ip = ""
cluster_name = "cluster0"

Connect to Cluster#

We now make a connection with the Cluster.

from qblox_instruments import Cluster, ClusterType

try:  # Close the chosen QCodes instrument to prevent name clash
except KeyError:

cluster = Cluster(
        2: ClusterType.CLUSTER_QCM,
        4: ClusterType.CLUSTER_QRM,
        6: ClusterType.CLUSTER_QCM_RF,
        8: ClusterType.CLUSTER_QRM_RF,
    if cluster_ip is None
    else None,

Get connected modules#

def get_connected_modules(cluster, filter_fn=None):
    def checked_filter_fn(mod):
        if filter_fn is not None:
            return filter_fn(mod)
        return True

    return {
        mod.slot_idx: mod for mod in cluster.modules if mod.present() and checked_filter_fn(mod)
# QRM baseband modules
modules = get_connected_modules(cluster, lambda mod: mod.is_qrm_type and not mod.is_rf_type)
{4: <QcmQrm: cluster0_module4 of Cluster: cluster0>}
module = modules[4]

Reset the Cluster#

We reset the Cluster to enter a well-defined state. Note that resetting will clear all stored parameters, so resetting between experiments is usually not desirable.

Status: OKAY, Flags: NONE, Slot flags: NONE

Generate waveforms#

Next, we need to create the gaussian and block waveforms for the sequence. The waveforms constructed here will be referenced by the Q1ASM program for playback. See section Sequencer for details on how waveform dictionary is structured.

Waveform resolution notes

# Waveform parameters
waveform_length = 22  # nanoseconds

# Waveform dictionary (data will hold the samples and index will be used to select the waveforms in the instrument).
waveforms = {
    "gaussian": {
        "data":, std=0.12 * waveform_length).tolist(),
        "index": 0,
    "block": {"data": [1.0 for i in range(0, waveform_length)], "index": 1},

Let’s plot the waveforms to see what we have created.

time = np.arange(0, max(map(lambda d: len(d["data"]), waveforms.values())), 1)
fig, ax = plt.subplots(1, 1, figsize=(10, 10 / 1.61))

for wf, d in waveforms.items():
    ax.plot(time[: len(d["data"])], d["data"], ".-", linewidth=0.5, label=wf)

ax.grid(alpha=1 / 10)
ax.set_ylabel("Waveform primitive amplitude")
ax.set_xlabel("Time (ns)")


Create Q1ASM program#

Now that we have the waveforms for the sequence, we need a Q1ASM program that sequences the waveforms as previously described. The Q1ASM program can address the memory in the sequences waveforms and acquisitions to construct a program for playback. View Q1 Programming for a break down of available instructions in the Q1ASM language.

# Sequence program.
seq_prog = """
       move      100,R0   #Loop iterator.
       move      20,R1    #Initial wait period in ns.
       wait_sync 4        #Wait for sequencers to synchronize and then wait another 4 ns.

loop:  set_mrk   1        #Set marker output 1.
       play      0,1,4    #Play a gaussian and a block on output path 0 and 1 respectively and wait 4 ns.
       set_mrk   0        #Reset marker output 1.
       upd_param 18       #Update parameters and wait the remaining 18 ns of the waveforms.

       wait      R1       #Wait period.

       play      1,0,22   #Play a block and a gaussian on output path 0 and 1 respectively and wait 22 ns.
       wait      1000     #Wait a 1us in between iterations.
       add       R1,20,R1 #Increase wait period by 20 ns.
       loop      R0,@loop #Subtract one from loop iterator.

       stop               #Stop the sequence after the last iteration.

Prepare and Upload sequence#

Now that we have the waveforms and Q1ASM program, we can combine them in a sequence stored in a JSON file.

# Add sequence to single dictionary and write to JSON file.
sequence = {
    "waveforms": waveforms,
    "weights": {},
    "acquisitions": {},
    "program": seq_prog,
with open("sequence.json", "w", encoding="utf-8") as file:
    json.dump(sequence, file, indent=4)

Let’s write the JSON file to the instruments. We will use sequencer 0 and 1, which will drive outputs \(\text{O}^{[1-2]}\) and \(\text{O}^{[3-4]}\) respectively.

# Upload sequence.

Play sequence#

The sequence has been uploaded to the instrument. Now we need to configure the sequencers in the instrument to use the wait_sync instruction at the start of the Q1ASM program to synchronize.

# Configure the sequencers to synchronize.

# Map sequencers to specific outputs (but first disable all sequencer connections).

# If it is a QRM, we only map sequencer 0 to the outputs.
if module.is_qcm_type:

Now let’s start the sequence. If you want to observe the sequence, this is the time to connect an oscilloscope to marker output 1 and one or more of the four outputs. Configure the oscilloscope to trigger on the marker output 1.

# Arm and start both sequencers.

# Print status of both sequencers.
Status: STOPPED, Flags: NONE
Status: STOPPED, Flags: NONE


Finally, let’s stop the sequencers if they haven’t already and close the instrument connection. One can also display a detailed snapshot containing the instrument parameters before closing the connection by uncommenting the corresponding lines.

# Stop both sequencers.

# Print status of both sequencers (should now say it is stopped).

# Uncomment the following to print an overview of the instrument parameters.
# Print an overview of the instrument parameters.
# print("Snapshot:")
# module.print_readable_snapshot(update=True)

# Reset the cluster

Status: OKAY, Flags: NONE, Slot flags: NONE