See also

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

Mixer correction#

In this tutorial we will demonstrate the ability to compensate for output mixer non-idealities and observe the changes using an oscilloscope.

Mixer non-idealities can lead to unwanted spurs on the output (LO/RF/IF feedthrough and other spurious products) and they can be compensated by applying adjustments to the I/Q outputs: phase offset, gain ratio and DC offset. This solution applies to both baseband QCM/QRM products using external mixers as well as QCM-RF and QRM-RF products.

The tutorial is designed for Cluster QRM/QCM baseband. We will adjust all the parameters listed above and observe the changes to the I/Q outputs directly on an oscilloscope.

For QCM-RF and QRM-RF products, one can also refer to the ‘mixer calibration’ section of the tutorial on RF-control.

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

# Set up the environment.
from IPython.display import display
from ipywidgets import interact
from qcodes import Instrument

from qblox_instruments import Cluster, PlugAndPlay

Scan For Clusters#

We scan for the available clusters on our network using the Plug & Play functionality of the Qblox Instruments package (see Plug & Play for more info).

# Scan for available devices and display
with PlugAndPlay() as p:
    # get info of all devices
    device_list = p.list_devices()

names = {dev_id: dev_info["description"]["name"] for dev_id, dev_info in device_list.items()}
ip_addresses = {dev_id: dev_info["identity"]["ip"] for dev_id, dev_info in device_list.items()}

# create widget for names and ip addresses
connect = widgets.Dropdown(
    options=[(names[dev_id] + " @" + ip_addresses[dev_id], dev_id) for dev_id in device_list],
    description="Select Device",

Connect to Cluster#

We now make a connection with the Cluster selected in the dropdown widget. We also define a function to find the modules we’re interested in. We select the readout and control module we want to use.

# Connect to device
dev_id = connect.value
# Close the chosen QCodes instrument as to prevent name clash.

# PlugAndPlay assigns an instrument name with a hyphen. For example 'pulsar-qrm' as a string for instrument name.
# QCodes instrument class cannot handle hyphens, and changes them to underscore '_'.
# However, this happens only once with a warning and never again, so code does not work. This line does the automation for it.
names[dev_id] = names[dev_id].replace("-", "_")

with contextlib.suppress(KeyError):

cluster = Cluster(name=names[dev_id], identifier=ip_addresses[dev_id])

print(f"{connect.label} connected")
Marketing-Cluster @ connected
Status: OKAY, Flags: NONE, Slot flags: NONE
def select_module_widget(device, select_all=False, select_rf_type: bool = False):
    Create a widget to select modules of a certain type.

    default is to show only QRM baseband

        devices : Cluster we are currently using
        select_all (bool): ignore filters and show all modules
        select_rf_type (bool): filter RF/baseband
    options = [[None, None]]

    for module in device.modules:
        if module.present() and (select_all or module.is_rf_type == select_rf_type):
                    f"{} "
                    f"{module.short_name} "
                    f"({module.module_type}{'_RF' if module.is_rf_type else ''})",
    widget = widgets.Dropdown(options=options)

    return widget

print("Select QCM or QRM module from the available ones:")
select_module = select_module_widget(cluster, select_rf_type=False)
Select QCM or QRM module from the available ones:
# Connect to the cluster QCM/QRM module
module = select_module.value
print(f"{module} connected")
<QcmQrm: Marketing-Cluster_module13 of Cluster: Marketing-Cluster> connected
Status: OKAY, Flags: NONE, Slot flags: NONE

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.

[ ]:

Setup Sequencer#

The easiest way to view the influence of the mixer correction is to mix the NCO sin and cos with I and Q values of 1 (fullscale). The instrument output would be simple sinusoids with a 90[deg] phase offset and identical amplitude.

We use sequencer 0 to set I and Q values of 1 (fullscale) using DC offset and we mix those with the NCO signals.

# Program sequence we will not use.
sequence = {"waveforms": {}, "weights": {}, "acquisitions": {}, "program": "stop"}
with open("sequence.json", "w", encoding="utf-8") as file:
    json.dump(sequence, file, indent=4)

# Program fullscale DC offset on I & Q, turn on NCO and enable modulation.

Control sliders#

Create control sliders for the parameters described in the introduction. Each time the value of a parameter is updated, the sequencer is automatically stopped from the embedded firmware for safety reasons and has to be manually restarted.

The sliders cover the valid parameter range. If the code below is modified to input invalid values, the firmware will not program the values.

Please connect the I/Q outputs (\(\text{O}^{[1-2]}\)) to an oscilloscope and set to trigger continuously on the I channel at 0V. Execute the code below, move the sliders and observe the result on the oscilloscope.

def set_offset_I(offset_I):

def set_offset_Q(offset_Q):

def set_gain_ratio(gain_ratio):

def set_phase_offset(phase_offset):

I_bounds = module.out0_offset.vals.valid_values
        min=I_bounds[0], max=I_bounds[1], step=0.01, value=0.0, description="Offset I:"

Q_bounds = module.out1_offset.vals.valid_values
        min=Q_bounds[0], max=Q_bounds[1], step=0.01, value=0.0, description="Offset Q:"

# The gain ratio correction is bounded between 1/2 and 2
        min=-1, max=1, step=0.1, value=1.0, base=2, description="Gain ratio:"

ph_bounds = module.sequencer0.mixer_corr_phase_offset_degree.vals.valid_values
        min=ph_bounds[0], max=ph_bounds[1], step=1.0, value=0.0, description="Phase offset:"
<function __main__.set_phase_offset(phase_offset)>

When tuning the DC offset you might notice that the signal starts “clipping”. This is caused by the fact that we are already at full-scale, thus any offset takes our signal out of its dynamic range.

When this happens, the output LEDs on the module turn orange. This, and other LEDs states, are explained in the troubleshooting guide.

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