Quick Start Guide

Import the toolkit from the zhinst namespace as follows:

import zhinst.toolkit as tk

Initialize the device

The toolkit provides instrument drivers for multiple different Zurich Instruments devices. It includes drivers for

• HDAWG

• MFLI

• PQSC

• SHFQA

• UHFLI

• UHFQA

All of the instrument drivers available in the toolkit share some basic device properties. Every device is identified by a name and a serial number. The name is free for the user to chose and only for their convenience. The serial however, is a unique identifier for every Zurich Instruments device. The serial number can be found on the back panel of instrument and is of the format DEV1234. In addition, the toolkit needs to know what interface the device uses and where to find the data server (host). The value for the interface defaults to a connection via Ethernet (1GbE) and the host address is localhost unless specified otherwise.

As a first example, we now initialize the instrument driver for a HDAWG. We name it hdawg1 and we know that our device’s serial number is dev8030.

hdawg = tk.HDAWG("hdawg1", "dev8030", interface="1gbe", host="10.42.0.226")

hdawg.setup()           # set up data server connection
hdawg.connect_device()  # connect device to data server

Successfully connected to data server at 10.42.0.2268004 api version: 6
Successfully connected to device DEV8030 on interface 1GBE

The methods setup() and connect_device() initialize the data server and connect the device to it. Now the device is connected and ready to go.

Every instrument driver in the toolkit features some properties with basic information about the device. What was the device’s serial number again? What options are installed?

print(f"name:        {hdawg.name}")
print(f"serial:      {hdawg.serial}")
print(f"device:      {hdawg.device_type}")
print(f"options:     {hdawg.options}")
print(f"interface:   {hdawg.interface}")
print(f"connected:   {hdawg.is_connected}")

name:        hdawg1
serial:      dev8030
device:      DeviceTypes.HDAWG
options:     ['MF', 'CNT', 'ME', 'PC', 'SKW']
interface:   1gbe
connected:   True

Access the device’s nodetree

The driver’s property nodetree is a data structure that allows the user to access all the settings and data on the device. The settings are highly structured into logical groups, enumerations and options.

For example, all of the device’s signal inputs and all of its signal outputs are grouped together. Also the HDAWG’s eight sine generators are grouped into sines that are then enumerated from 0 - 7. Each Node in the nodetree as well as the nodetree itself can have other Nodes or Parameters as attributes. The Parameters are the ‘leaves’ of the tree data structure and represent individual settings or data on the instrument.

HDAWG
└── nodetree
    │
    └─── sigouts             <--- Node List
    │    └─── 0              <--- Node
    │    │    └─── on        <--- Prameter
    │    │    └─── range
    │    │    └─── direct
    │    │    └─── offset
    │    │    └─── ...
    │    └─── 1
    │    └─── ...
    │
    └─── oscs
    │    └─── 0
    │    │    └─── freq
    │    └─── 1
    │    └─── 2
    │    └─── ...
    │
    └─── sines
    │    └─── ...
    │
    └─── dio
    │    └─── ...
    │
    └─── ...

Enumerated nodes such as the eight sine-generators or 16 oscillators of the HDAWG are grouped together in lists. For example the node of the first sine-generator would be accessed via hdawg.nodetree.sines[0].

In a Jupyter notebook or a console it is easy to navigate through the NodeTree. At every given node, the object representation shows a list of all the available sub-nodes and parameters. In this way it is easy to find the exact setting you might need.

hdawg.nodetree

<zhinst.toolkit.control.nodetree.Nodetree object at 0x00000224A97F8908>
nodes:
 - stats
 - oscs
 - status
 - sines
 - awgs
 - dio
 - system
 - sigouts
 - triggers
 - features
 - cnts
parameters:
 - clockbase

hdawg.nodetree.sines[0:2]

[<zhinst.toolkit.control.nodetree.Node object at 0x00000224AE08EF60>
 nodes:
  - enables
  - amplitudes
 parameters:
  - oscselect
  - phaseshift
  - harmonic,
 <zhinst.toolkit.control.nodetree.Node object at 0x00000224AE093160>
 nodes:
  - enables
  - amplitudes
 parameters:
  - oscselect
  - phaseshift
  - harmonic]

At the end of the tree, the leaves, are zhinst-toolkit Parameters. In case you wonder what a certain parameter does, its object representation offers an insightful description.

hdawg.nodetree.oscs[0].freq

Node: /DEV8030/OSCS/0/FREQ
Description: Frequency control for each oscillator.
Type: Double
Properties: Read, Write, Setting
Unit: Hz

The parameters are callable to set and get the instrument values.

# set oscillator frequency to 100 MHz
hdawg.nodetree.oscs[0].freq(100e6)

# what frequency is the oscillator set to now?
hdawg.nodetree.oscs[0].freq()

99999999.99999432

The instrument driver’s nodetree property is created whenever it connects the device to the data server. This ensures that the available nodes and parameters in the nodetree are always up to date with the latest version of the device’s firmware.

Depending on the device, the instrument drivers also have properties other than the nodetree. Those are called Modules and depend on the type of device at hand and the options installed on it. Modules can for example be the Data Acquisition Module or the Sweeper Module. The devices with AWGs such as the HDAWG, UHFQA and the UHFLI (if option is installed) feature AWG Modules. Each AWG Module controls two chanels and features high-level functionality for programming sequences of waveforms and generating IQ-Modulation signals.

For more information, see the package documentation of the zhinst-toolkit and the following examples.

How to Use zhinst-toolkit A Tour of the Instrument Drivers