Acquisitions#

Introduction#

This tutorial provides examples of how to add acquisitions to schedules and retrieve the corresponding results.

The fundamental data structure returned by an acquisition is an xarray.Dataset (official documentation), which consists of multiple xarray.DataArray.

Initial setup#

First, we set up the connection to the cluster and hardware configuration.

The introduction and parametrization of a qubit is not mandatory for running acquisitions. Hence schedules presented in this tutorial will remain at the pulse-level description.

[1]:

from typing import Any

import xarray

from qblox_scheduler import HardwareAgent

[2]:

hardware_config: dict[str, Any] = {
    "version": "0.2",
    "config_type": "QbloxHardwareCompilationConfig",
    "hardware_description": {
        "cluster0": {
            "instrument_type": "Cluster",
            "modules": {"4": {"instrument_type": "QRM"}},
            "ref": "internal",
        }
    },
    "hardware_options": {},
    "connectivity": {
        "graph": [
            ["cluster0.module4.complex_output_0", "q0:port"],
            ["cluster0.module4.complex_input_0", "q0:port"],
        ]
    },
}

hardware_agent: HardwareAgent = HardwareAgent(hardware_configuration=hardware_config)
hardware_agent.connect_clusters()
# note: if the call to the connect_cluster method is dropped, it would happen anyway automatically at the next call to
#       a run method. Using connect_cluster explicitly is therefore not mandatory.

/builds/0/.venv/lib/python3.10/site-packages/qblox_scheduler/qblox/hardware_agent.py:460: UserWarning: cluster0: Trying to instantiate cluster with ip 'None'.Creating a dummy cluster.
  warnings.warn(

Pulse-level acquisitions#

Pulse-level acquisitions define when and how to store and retrieve input signals coming from the device. They are described by their timing information (start time and length), protocol, acq_channel and coordinates.

Timing information specifies when the acquisition happens on the schedule.
Protocol defines which hardware or software formatting is done on the input signal.
acq_channel and coords together identify acquisitions and data points for the user in the returned dataset: acq_channel identifies a particular DataArray, while every point within such an array is identified by coordinates.

In the following subsections we give examples for each supported acquisition protocol.

We assume, that these tutorials are run on a Qblox QRM module. On the QRM module \(\text{O}^{[1]}\) is connected to \(\text{I}^{[1]}\) and \(\text{O}^{[2]}\) is connected to \(\text{I}^{[2]}\).

The physical length of the cables connecting output to input channels introduces a delay before a sent signal is received. This delay is known as the TIME_OF_FLIGHT.

Trigger count acquisition#

The trigger count acquisition protocol is used for measuring how many times the input signal goes over some limit. This protocol is used, for example, in cases where one wants to count the number of detection events in an experiment.

The trigger count protocol is currently only available on two module types: the QRM (baseband) and the QTM.

Similarly to what was discussed above with the single-sideband integration acquisition protocol, we can make use of the coords argument to append and/or sum the number of trigger events received during a given acquisition window. If a loop reference is set as being a coordinate of the acquisition, the number of counts is appended is appended at each iteration of the loop.

In addition to the integration and appending bin modes the TriggerCount protocol offers the distribution bin mode, which can only be used with the QRM.

In the distribution bin mode, the result is a distribution that maps the trigger count numbers to the number of occurrences of each trigger count number. This provides insights into the overall occurrence of triggers when running the acquisition multiple times. For example, imagine an experiment where a TriggerCount acquisition runs three times and detects [1, 3, 1] triggers respectively. In distribution mode, the instrument directly compiles a histogram of these results. It would report that a count of ‘1’ occurred twice and a count of ‘3’ occurred once, returning a result like {1: 2, 3: 1}. The dictionary notation shows the number of triggers as keys and their corresponding frequencies as values.

The threshold is set for the QRM via the TTL acquisition threshold field, while for the QTM this threshold is set via the field analog_threshold in the digitization threshold hardware option.

Setup and schedule#

Let’s have an illustrative example showing how this type of acquisition works in practice.

We use a source of random dirac pulses that we made up with a function generator: it plays a 20ns wide TTL pulse in burst mode, externally triggered with a source of noise. The ratio between the burst trigger level of the function generator, and the RMS amplitude of the noise sets the average flux of pulses emitted by the source. In practice we set it up to have a flux of a few pulses per micro-second.

This source of random pulses is then connected to the second input of a QRM module, to proceed to the detection and counting.

Let’s first set up the hardware configuration for this experiment. We will set up the counting threshold of the QRM to 60% of the maximum input amplitude (so 0.6 x 0.5V = 300mV).

We will perform the acquisitions in a window of 15us:

[35]:

ACQ_DURATION: float = 15e-6

[36]:

hardware_cfg_trigger_count: dict[str, Any] = {
    "config_type": "QbloxHardwareCompilationConfig",
    "version": "0.2",
    "hardware_description": {
        "cluster0": {
            "instrument_type": "Cluster",
            "modules": {
                4: {"instrument_type": "QRM"},
            },
            "ref": "internal",
        },
    },
    "hardware_options": {
        "sequencer_options": {
            "qrm:in1-digital": {
                "ttl_acq_threshold": 0.6,
            }
        },
    },
    "connectivity": {
        "graph": [
            ["cluster0.module4.complex_output_0", "qrm:out"],
            ["cluster0.module4.real_input_0", "qrm:in0"],
            ["cluster0.module4.real_input_1", "qrm:in1"],
        ]
    },
}

hardware_agent: HardwareAgent = HardwareAgent(hardware_configuration=hardware_cfg_trigger_count)
hardware_agent.connect_clusters()

/builds/0/.venv/lib/python3.10/site-packages/qblox_scheduler/qblox/hardware_agent.py:460: UserWarning: cluster0: Trying to instantiate cluster with ip 'None'.Creating a dummy cluster.
  warnings.warn(

First check: scope acquisition#

We will start by simply performing a scope acquisition of the signal, to verify how it looks.

[37]:

from qblox_scheduler import Schedule
from qblox_scheduler.operations import Trace

schedule: Schedule = Schedule("trace_acquisition_tutorial")

schedule.add(
    Trace(duration=ACQ_DURATION, acq_channel="scope", port="qrm:in1", clock="cl0.baseband")
)

xr_ttl_trace_acquisition: xarray.Dataset = hardware_agent.run(schedule)

Invalid input indices are connected. Scope data might be invalid. Connected input indices are (1,). Valid indices are (0, 1) and (2, 3).

[38]:

import xarray as xr

xr_ttl_trace_acquisition = xr.open_dataset(
    "./utils/data/trigger_count_scope.hdf5", engine="h5netcdf"
)

[39]:

import matplotlib.pyplot as plt

fig, ax = plt.subplots(figsize=(10, 4))

xr_ttl_trace_acquisition["scope"].imag.plot(ax=ax)

ax.set_xlabel("Time (ns)")
ax.set_ylabel("Amplitude (a.u.)")
ax.set_title("Acquired trace")
ax.set_ylim(-0.1, 1.0)
ax.grid()

../../../../_images/products_qblox_scheduler_tutorials_any_acquisitions_66_0.png

Appending the counts#

We will repeat a TriggerCount acquisition, appending all the result until we entirely filled the instrument memory (currently set to a maximum of 131_072 bins).

[40]:

from qblox_scheduler import Schedule
from qblox_scheduler.operations import TriggerCount
from qblox_scheduler.operations.loop_domains import DType

REPS: int = 131_072  # maximum number of bins usable on instrument memory

schedule: Schedule = Schedule("trigger_count_acquisition_tutorial")

with schedule.loop(arange(0, REPS, 1, dtype=DType.NUMBER)) as rep:
    schedule.add(
        TriggerCount(
            duration=ACQ_DURATION,
            port="qrm:in1",
            clock="cl0.baseband",
            acq_channel="counts",
            coords={"rep": rep},
        )
    )
xr_ttl_append_counts_acquisition: xarray.Dataset = hardware_agent.run(schedule)

[41]:

import xarray as xr

xr_ttl_append_counts_acquisition = xr.open_dataset(
    "./utils/data/trigger_count_append.hdf5", engine="h5netcdf"
)

Let’s now plot the histogram of the 131k appended counts, as well as the gaussian that we can extract from the computation of the mean value and standard deviation of this data series.

[42]:

fig, ax = plt.subplots()

avg = xr_ttl_append_counts_acquisition["counts"].mean().item()
std = xr_ttl_append_counts_acquisition["counts"].std().item()

x = np.linspace(0, 40, 100)
y = np.exp(-0.5 * ((x - avg) / std) ** 2) * REPS / (std * np.sqrt(2 * np.pi))

xr_ttl_append_counts_acquisition["counts"].plot.hist(
    bins=list(range(41)), edgecolor="black", align="left", ax=ax, label="Appended data histogram"
)
ax.plot(x, y, color="tab:red", ls="dashed", lw=2, label="Gaussian fit")


ax.legend()
ax.set_xlabel("Counts")
ax.set_ylabel("Occurrences")
ax.set_title(f"Histogram of Trigger Counts over {REPS} repetitions")
ax.text(30, 6000, f"Mean: {avg:.2f}\nStd: {std:.2f}")

[42]:

Text(30, 6000, 'Mean: 19.43\nStd: 3.72')

../../../../_images/products_qblox_scheduler_tutorials_any_acquisitions_71_1.png

We therefore measured a flux of \(1.3 \pm 0.2\) pulse/sec

Distribution mode#

From what was explained before, it is clear that above histogram could have been obtained in one step (i.e. without data analysis function) using the distribution bin mode.

Not only it spares us from doing any post-analysis of the raw data (the histogram binning is happening on the instrument side), but also – and more importantly – we no longer saturates the instrument memory, meaning that the acquisition can be iterated much longer: let’s do it for a million of iteration.

[43]:

from qblox_scheduler import Schedule
from qblox_scheduler.operations import TriggerCount
from qblox_scheduler.operations.acquisition_library import BinMode
from qblox_scheduler.operations.loop_domains import DType

REPS: int = 1_000_000  # maximum number of bins usable on instrument memory

schedule: Schedule = Schedule("trigger_count_acquisition_tutorial")

with schedule.loop(arange(0, REPS, 1, dtype=DType.NUMBER)) as rep:
    schedule.add(
        TriggerCount(
            duration=ACQ_DURATION,
            port="qrm:in1",
            clock="cl0.baseband",
            acq_channel="occurrence",
            bin_mode=BinMode.DISTRIBUTION,
        )
    )
xr_data_distr: xarray.Dataset = hardware_agent.run(schedule)

[44]:

import xarray as xr

xr_data_distr = xr.open_dataset("./utils/data/trigger_count_distr.hdf5", engine="h5netcdf")

[45]:

fig, ax = plt.subplots()

avg = np.average(xr_data_distr["counts_occurrence"], weights=xr_data_distr["occurrence"]).item()
std = np.sqrt(
    np.average((xr_data_distr["counts_occurrence"] - avg) ** 2, weights=xr_data_distr["occurrence"])
).item()

x = np.linspace(0, 40, 100)
y = np.exp(-0.5 * ((x - avg) / std) ** 2) * REPS / (std * np.sqrt(2 * np.pi))

ax.plot(x, y, color="tab:red", ls="dashed", lw=2, label="Gaussian fit")
xr_data_distr["occurrence"].plot(
    x="counts_occurrence",
    marker="o",
    ls="None",
    color="tab:green",
    ax=ax,
    label="Distribution data points",
)


ax.legend()
ax.set_xlabel("Counts")
ax.set_ylabel("Occurrences")
ax.set_title(f"Histogram of Trigger Counts over {REPS} repetitions")
ax.text(30, 40000, f"Mean: {avg:.2f}\nStd: {std:.2f}")

[45]:

Text(30, 40000, 'Mean: 19.46\nStd: 3.71')

../../../../_images/products_qblox_scheduler_tutorials_any_acquisitions_76_1.png

[46]:

avg = 19.43
std = 3.71


def gaussian(x):
    return np.exp(-0.5 * ((x - avg) / std) ** 2) / (std * np.sqrt(2 * np.pi))


x = np.linspace(0, 40, 1000)
y = gaussian(x)

fig, ax = plt.subplots(figsize=(10, 5))
# vertical line at 17 below the curve
ax.axvline(17, color="red", ls="dashed", lw=2, ymin=0.04, ymax=0.78, label="Movable threshold")
ax.plot(x, y, color="k", lw=2)


# shade area under the curve to the left of 17
x_fill_left = np.linspace(0, 17, 200)
y_fill_left = y = gaussian(x_fill_left)

x_fill_right = np.linspace(17, 40, 200)
y_fill_right = y = gaussian(x_fill_right)

ax.fill_between(
    x_fill_left,
    y_fill_left,
    color="lightgreen",
    alpha=0.5,
    label="Below threshold $\\rightarrow$ 1",
)
ax.fill_between(
    x_fill_right,
    y_fill_right,
    color="lightblue",
    alpha=0.5,
    label="Above threshold $\\rightarrow$ 0",
)

ax.set_xlabel("Counts")
ax.set_ylabel("Probability density")
ax.grid()
ax.legend()

plt.savefig("./utils/images/thresholded_acquisition_schematic.png", dpi=300)
plt.close(fig)

Thresholded trigger count acquisition#

Generalities#

The thresholded trigger count protocol combines the functionality of the trigger count acquisition with a final comparison step. It first counts the rising edges of an input signal over a duration and then compares this total count to a specified integer threshold. The threshold comparison result (False (0), or True (1)) can be retrieved directly, and can also be used to conditionally execute other instructions. For the latter, you would use the ConditionalOperation.

We propose here to keep using our source of random pulses for illustrating this acquisition protocol. We still use 15us long acquisition windows, within which the pulses are counted. As shown in the figure below, if the number of counts is smaller than the threshold, we trigger an event on the cluster internal network, and we count the acquisition as a 1, otherwise no event is triggered and we count it as a 0.

By scanning over the value \(n_{th}\) of the threshold, the probability \(P_1(n_{th})\) of having the acquisition returning 1 should follow the erf error function, corresponding the antiderivative of the gaussian.

Schedule and verification with an oscilloscope#

The source of pulses is connected to the input 1 of the QRM. An oscilloscope is connected to the output channels of the QRM, for checking if the conditionally triggered operation are correctly executed. We start by writing a simple schedule:

a 1us long square pulse is played by the QRM: it is used to trigger a single acquisition with the oscilloscope;
we wait 1us;
the acquisition starts, it lasts 15us and an event is send on the trigger network (label “click”) if at least 1 count has been detected: regarding the typical number of pulses detected in 15us (see above), this effectively ensures the emission of an event;
a negative square pulse is played, triggered by the event on the “click” channel;

[47]:

from qblox_scheduler import Schedule
from qblox_scheduler.operations import (
    ConditionalOperation,
    IdlePulse,
    SquarePulse,
    ThresholdedTriggerCount,
)

schedule: Schedule = Schedule("Conditional operation")
schedule.add(SquarePulse(amp=1, duration=1e-6, port="qrm:out", clock="cl0.baseband"))
schedule.add(IdlePulse(duration=1e-6))
schedule.add(
    ThresholdedTriggerCount(
        port="qrm:in1",
        clock="cl0.baseband",
        duration=15e-6,
        threshold=1,  # very small threshold to ensure a trigger
        feedback_trigger_label="click",  # label of the trigger to be used in the ConditionalOperation
    )
)
schedule.add(
    ConditionalOperation(
        body=SquarePulse(amp=-1, duration=1e-6, port="qrm:out", clock="cl0.baseband"),
        qubit_name="click",
    ),
)
schedule.add(IdlePulse(4e-9))

[47]:

{'name': 'f8922d80-eadf-4397-a42f-16f451ce3aff', 'operation_id': '1965641272212533360', 'timing_constraints': [TimingConstraint(ref_schedulable=None, ref_pt=None, ref_pt_new=None, rel_time=0)], 'label': 'f8922d80-eadf-4397-a42f-16f451ce3aff'}

[48]:

import numpy as np
from matplotlib import pyplot as plt

scope_data = np.genfromtxt(
    "./utils/data/conditional_playback_wf.csv",
    delimiter=",",
    skip_header=12,
)


fig, ax = plt.subplots(figsize=(12, 4))

arr_time, arr_trace = scope_data[:, 0], scope_data[:, 1]

ax.axvspan(1, 2, color="pink", alpha=0.5)
ax.axvspan(2, 17, color="tab:green", alpha=0.2)
ax.text(9.5, 0.25, "Acquisition", fontsize=12, ha="center", color="green")
ax.plot(arr_time * 1e6, arr_trace)

ax.set_xlabel("Time (us)")
ax.set_ylabel("Amplitude (V)")
ax.set_title("Acquired trace after conditional operation triggered")
ax.grid()

plt.tight_layout()
plt.savefig("./utils/images/conditional_playback_trace.png", dpi=300)
plt.close(fig)

Let’s plot the trace acquired by the scope is indeed showing two pulses of opposite polarities, and check that the duration between both pulses is indeed the expected one:

[49]:

threshold: float = 0.5
above_threshold: np.ndarray = arr_trace > threshold
below_threshold: np.ndarray = arr_trace < -threshold
first_pulse_timestamp: int = np.where(above_threshold)[0][0]
second_pulse_timestamp: int = np.where(below_threshold)[0][0]
delta_t: int = arr_time[second_pulse_timestamp] - arr_time[first_pulse_timestamp]
print(f"Delay time between pulses: {delta_t * 1e6:.1f} us")

Delay time between pulses: 17.0 us

Let’s now proceed to the complete experiment, where the threshold value is scanned, and for each value of the threshold we perform 100_000 iteration of the ThresholdedTriggerCount acquisition.

[50]:

from qblox_scheduler import Schedule
from qblox_scheduler.enums import TriggerCondition
from qblox_scheduler.operations import (
    ConditionalOperation,
    IdlePulse,
    SquarePulse,
    ThresholdedTriggerCount,
)

datasets: list[xarray.Dataset] = []
for threshold in range(40):
    schedule: Schedule = Schedule("Conditional operation")

    schedule.add(SquarePulse(amp=1, duration=1e-6, port="qrm:out", clock="cl0.baseband"))
    schedule.add(IdlePulse(duration=1e-6))

    with schedule.loop(arange(0, 100_000, 1, dtype=DType.NUMBER)) as rep:
        schedule.add(
            ThresholdedTriggerCount(
                port="qrm:in1",
                clock="cl0.baseband",
                duration=15e-6,
                threshold=threshold,
                feedback_trigger_label="click",
                acq_channel="thresholded_count",
                feedback_trigger_condition=TriggerCondition.LESS_THAN,
            )
        )
        schedule.add(
            ConditionalOperation(
                body=SquarePulse(amp=-1, duration=1e-6, port="qrm:out", clock="cl0.baseband"),
                qubit_name="click",
            ),
        )
        schedule.add(IdlePulse(4e-9))

    datasets.append(hardware_agent.run(schedule))

[51]:

import pickle as pkl
from pathlib import Path

source_file = Path("./utils/data/datasets.pkl")
with source_file.open("rb") as f:
    datasets = pkl.load(f)

[52]:

cumulative_probability: list[float] = []
for dataset in datasets:
    cumulative_probability.append(dataset.thresholded_count.sum().item() / 100_000)

fig, ax = plt.subplots(figsize=(10, 5))
ax.plot(range(40), cumulative_probability, marker="o")
ax.set_xlabel("Threshold")
ax.set_ylabel("Probability")
ax.set_title("Cumulative probability to detect a trigger vs threshold")
ax.grid()

../../../../_images/products_qblox_scheduler_tutorials_any_acquisitions_87_0.png

Acquisitions#

Introduction#

Initial setup#

Pulse-level acquisitions#

Trace acquisition#

Setting up the schedule#

Compile and run the schedule, retrieving acquisition#

Single-sideband integration acquisition#

Setting up the schedule#

Running the schedule, retrieving acquisition#

Acquisition coordinates#

General concept#

Sparse and dense representation of the data#

Averaging during the acquisition#

Weighted single-sideband integration acquisition#

Thresholded acquisition#

Setting up the schedule#

Trigger count acquisition#

Setup and schedule#

First check: scope acquisition#

Appending the counts#

Distribution mode#

Thresholded trigger count acquisition#

Generalities#

Schedule and verification with an oscilloscope#