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

Setup#

First, we are going to import the required packages.

[1]:
from __future__ import annotations

import json
from typing import TYPE_CHECKING, Callable

import ipywidgets as widgets
from ipywidgets import interact
from qcodes.instrument import find_or_create_instrument

from qblox_instruments import Cluster, ClusterType

if TYPE_CHECKING:
    from qblox_instruments.qcodes_drivers.module import Module

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

[2]:
cluster_ip = "10.10.200.42"
cluster_name = "cluster0"

Connect to Cluster#

We now make a connection with the Cluster.

[3]:
cluster = find_or_create_instrument(
    Cluster,
    recreate=True,
    name=cluster_name,
    identifier=cluster_ip,
    dummy_cfg=(
        {
            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#

[4]:
def get_connected_modules(cluster: Cluster, filter_fn: Callable | None = None) -> dict[int, Module]:
    def checked_filter_fn(mod: ClusterType) -> bool:
        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)
    }
[5]:
# RF modules
modules = get_connected_modules(cluster, lambda mod: mod.is_rf_type)
modules
[5]:
{6: <Module: cluster0_module6 of Cluster: cluster0>,
 8: <Module: cluster0_module8 of Cluster: cluster0>,
 10: <Module: cluster0_module10 of Cluster: cluster0>}
[6]:
module = modules[8]

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.

[7]:
cluster.reset()
print(cluster.get_system_status())
Status: OKAY, Flags: NONE, Slot flags: NONE

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.

[8]:
# 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)
    file.close()
module.sequencer0.sequence(sequence)

# Program fullscale DC offset on I & Q, turn on NCO and enable modulation.
module.sequencer0.offset_awg_path0(1.0)
module.sequencer0.offset_awg_path1(1.0)
module.sequencer0.nco_freq(10e6)
module.sequencer0.mod_en_awg(True)

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.

[9]:
def set_offset_I(offset_I: float) -> None:
    module.out0_offset_path0(offset_I)
    module.arm_sequencer(0)
    module.start_sequencer(0)


def set_offset_Q(offset_Q: float) -> None:
    module.out0_offset_path1(offset_Q)
    module.arm_sequencer(0)
    module.start_sequencer(0)


def set_gain_ratio(gain_ratio: float) -> None:
    module.sequencer0.mixer_corr_gain_ratio(gain_ratio)
    module.arm_sequencer(0)
    module.start_sequencer(0)


def set_phase_offset(phase_offset: float) -> None:
    module.sequencer0.mixer_corr_phase_offset_degree(phase_offset)
    module.arm_sequencer(0)
    module.start_sequencer(0)


I_bounds = module.out0_offset_path0.vals.valid_values
interact(
    set_offset_I,
    offset_I=widgets.FloatSlider(
        min=I_bounds[0], max=I_bounds[1], step=0.01, value=0.0, description="Offset I:"
    ),
)

Q_bounds = module.out0_offset_path1.vals.valid_values
interact(
    set_offset_Q,
    offset_Q=widgets.FloatSlider(
        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
interact(
    set_gain_ratio,
    gain_ratio=widgets.FloatLogSlider(
        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
interact(
    set_phase_offset,
    phase_offset=widgets.FloatSlider(
        min=ph_bounds[0], max=ph_bounds[1], step=1.0, value=0.0, description="Phase offset:"
    ),
)
[9]:
<function __main__.set_phase_offset(phase_offset: 'float') -> 'None'>

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.

[10]:
cluster.reset()
print(cluster.get_system_status())
Status: OKAY, Flags: NONE, Slot flags: NONE