How to write a config file

In order to use qFabric to control AWGs, a config file is needed to specify the AWGs. The config file uses TOML, a configuration format that is easy to read. This page contains information about how to write a config file.

Create a TOML file

First, create a config file in any path you want with any name. In this tutorial, We name it example_config.toml. We recommend to place your config file in a location that is backed up regularly or version tracked.

Specify the config verison

In example_config.toml, add the following lines.

[config]
version = 1

This specify the version of the config. The latest config version is 1.

Config version history

v1: The first config version.

Add start and stop step information

Then we want to add information about the start step and the stop step. The start and stop steps are optional. They are inserted to the start and end of each sequence. They are useful for cases where a digital channel is needed to synchronize other AWG devices. Certain AWG devices may not run the last step in a sequence. In this case, the stop step is an empty step that do not change the output if not run.

[start_step]
use = true
duration = 10e-6
digital_channel_synchronize = 0  # comment out if no digital channel is used for synchronization

[stop_step]
use = true
duration = 10e-6

Set use to true or false to turn the start or stop steps on or off. Set duration to the desired duration of the step. The digital_channel_synchronize setting defines the digital channel used set to high during the start step to synchronize other AWG devices. If this line is deleted or commented, no digital channel is automatically turned on during the start step.

Add an AWG device

After that, We want to define an AWG device controlled by qFabric. We assume that the first device is a Spectrum Instruments m4i.6622 AWG device. qFabric has built-in support of this device.

To define this device, add the following lines.

[[awgs]]
name = "m4i6622_1"

segmenter_module = "qfabric.planner.segmenter.m4i6622"
segmenter_class = "M4i6622Segmenter"
device_module = "qfabric.programmer.device.m4i6622"
device_class = "M4i6622Device"

Here [[awgs]] specifies an entry added to the awg array of this config. We define the name of the AWG, which can be customized to any text.

We also define the dotted python module paths and class names that support this AWG model (See Add support for a different AWG for adding new AWG support), which are subclasses of Segmenter and Device. These classes can be in any module that can be imported by python.

After this, we define the arguments for the segmenter (M4i6622Segmenter):

# the following lines needs to be indented.
  [awgs.segmenter_config]
  analog_channels = [0, 1, 2, 3]
  digital_channels = [0, 1, 2]
  analog_channels_to_store_digital_data = [1, 2, 3]

All required parameters of the segmenter class must be defined here, under the same names as the argument names defined in the segmenter class __init__

The following arguments are required by any segmenter class:

  • analog_channels: List of analog channels defined on this device.

  • digital_channels: List of digital channels defined on this device.

Then we define the arguments for the device (M4i6622Device):

# the following lines needs to be indented.
  [awgs.device_config]
  resource = "/dev/spcm0"
  external_clock_frequency = 10000000

Again, all required parameters of the device class must be defined here (except the segmenter parameter, which is the segmenter object generated by the config above), under the same names as the argument name defined in the device class __init__.

The following arguments are required by any device class:

  • resource: Path to the AWG device.

Add another AWG device

To control more than one AWG devices, we can add another entry in the awg array:

[[awgs]]
name = "m4i6622_2"

segmenter_module = "qfabric.planner.segmenter.m4i6622"
segmenter_class = "M4i6622Segmenter"
device_module = "qfabric.programmer.device.m4i6622"
device_class = "M4i6622Device"

  [awgs.segmenter_config]
  analog_channels = [4, 5, 6, 7]
  digital_channels = [3, 4, 5]
  analog_channels_to_store_digital_data = [5, 6, 7]

  [awgs.device_config]
  resource = "/dev/spcm1"
  external_clock_frequency = 10000000

Note that the analog_channels or digital_channels defined by multple AWG devices cannot contain the same indices.

Use the config file

To use the config file, run the following code in python:

from qfabric import ExperimentManager

config_file_path = "example_config.toml"
manager = ExperimentManager(config_file_path)