Instrument Drivers¶

Base Instrument¶

class zhinst.toolkit.control.drivers.base.BaseInstrument(name: str, device_type: zhinst.toolkit.interface.interface.DeviceTypes, serial: str, **kwargs)¶

High-level controller for all Zurich Instrument devices.

It can be used by itself or inherited for device specific controllers. It provides information and functionality common to all devices, such as a name, serial number, device type, interface, etc.

The instrument holds a DeviceConnection which handles all the communication with the data server. It also initializes a NodeTree that is used to access all the settings in the device’s nodetree.

>>> import zhinst.toolkit as tk
>>> ...
>>> inst = tk.BaseInstrument("myDevice", tk.DeviceTypes.HDAWG, "dev9999", interface="USB")
>>> inst.setup()
Successfully connected to data server at localhost 8004 api version: 6
>>> inst.connect_device()
Successfully connected to device DEV9999 on interface USB
>>> inst.nodetree
>>> ...

Parameters

name (str) – Identifier for the instrument.
device_type (DeviceType) – Type enum of the device type.
serial (str) – Serial number of the device, e.g. ‘dev2281’. The serial number can be found on instrument back panel.

nodetree¶

A Nodetree object contains a data structure that recreates the nodetree hierarchy of the instrument settings. The leaves of the tree are Parameters that can be called to get and set the according value from the device. The Nodetree can be used to navigate all available device settings without having to know the exact node path of the setting. Alternatively, the node can always be accessed using the _set(…) and _get(…) methods.

Type: zhinst.toolkit.control.node_tree.NodeTree

name¶

Identifier for the instrument.

Type: str

device_type¶

Type enum of the device type.

Type: DeviceType

serial¶

Serial number of the device.

Type: str

interface¶

Type of the device interface used, can be specified as a keyword argument to __init__().

Type: str

is_connected¶

A flag that shows if the device has established a connection to the data server.

Type: bool

_get(command: str, valueonly: bool = True)¶

Getter for the instrument.

This method gets a node value from the device, specified by a node string. Passes the arguments to the getter of the DeviceConnection and the ZIConnection. Eventually this method wraps around daq.get(…) in zhinst.ziPython.

>>> hdawg._get("sigouts/0/on")
1

The method also supports wildcards in the node path that can be specified with ‘ * ‘ as a placeholder. The flag valueonly can be used to get the exact node of the values.

>>> hdawg._get("sigouts/*/on")
[1, 0, 0, 0, 0, 0, 0]
>>> hdawg._get("sigouts/*/on", valueonly=False)
{'sigouts/0/on': 1,
 'sigouts/1/on': 0,
 'sigouts/2/on': 0,
 'sigouts/3/on': 0,
 'sigouts/4/on': 0,
 'sigouts/5/on': 0,
 'sigouts/6/on': 0,
 'sigouts/7/on': 0}

Parameters: command (str) – A node string to the parameter.
Keyword Arguments: valueonly (bool) – A flag to select if only the value should be returned or a dict with node/value pairs (default: True)
Raises: ToolkitError – if called and the device is not yet connected to the data server.
Returns: The value of the parameter corresponding to the specified node. If valueonly=False the value is returned in a dict with the node as a key.

_set(*args)¶

Setter for the instrument.

This method sets a node value from the device, specified by a node string. Passes the arguments to the setter of the DeviceConnection and the ZIConnection. Eventually this method wraps around daq.set(…) in zhinst.ziPython.

>>> hdawg._set("sigouts/0/on", 1)

The method also supports wildcards in the node path that can be specified with ‘ * ‘ as a placeholder.

>>> hdawg._set("sigouts/*/on", 1)

Instead of specifying a single node path and a value, the user is free to pass a list of node / value pairs to the method to apply several settings at once with one call of the method.

>>> settings = [
>>>     ("sigouts/0/on", 1),
>>>     ("sigouts/0/range", 0.75),
>>>     ("sigouts/0/offset", 0.5),
>>>     ("sigouts/0/filter", 0),
>>>     ...
>>> ]
>>> hdawg._set(settings)

Raises: ToolkitError – If called and the device in not yet connected to the data server.
Returns: The value set on the device as returned from the API’s set(…) method.

connect_device(nodetree: bool = True) → None¶

Connects the device to the data server.

This method connects the device to the data server of its connection, initializes the NodeTree and applies initial device settings. A data server connection needs to be set up beforehand by calling setup().

Parameters: nodetree (bool) – If True, the NodeTree object will be initialized after connecting the device, otherwise not. (Default: True)

setup(connection: zhinst.toolkit.control.connection.ZIConnection = None) → None¶

Sets up the data server connection.

The details of the connection (host, port, api_level) can be specified as keyword arguments in the __init__() method. Alternatively the user can pass an existing ZIConnection to the data server to be used for the instrument.

Parameters: connection (ZIConnection) – An existing data server connection. If specified, this data server will be used to establish a DeviceConnection. (default: None)

HDAWG¶

class zhinst.toolkit.HDAWG(name: str, serial: str, **kwargs)¶

Bases: zhinst.toolkit.control.drivers.base.base.BaseInstrument

High-level driver for Zurich Instruments HDAWG.

Inherits from BaseInstrument and defines device specific methods and properties. The four AWG Cores of the HDAWG can be accessed through the property awgs that is a list of four AWGCore s that are specific for the device and inherit from the AWGCore class.

>>> from zhinst.toolkit import HDAWG
>>> ...
>>> hd = HDAWG("hdawg 1", "dev8030")
>>> hd.setup()
>>> hd.connect_device()
>>> hd.nodetree
<zhinst.toolkit.tools.node_tree.NodeTree object at 0x0000021E467D3BA8>
nodes:
- stats
- oscs
- status
- sines
- awgs
- dio
- system
- sigouts
- triggers
- features
- cnts
parameters:
- clockbase

Parameters

name (str) – Identifier for the HDAWG.
serial (str) – Serial number of the device, e.g. ‘dev1234’. The serial number can be found on the back panel of the instrument.

awgs¶

A list of four device-specific AWG Cores of type zhinst.toolkit.control.drivers.hdawg.AWG.

Type: list

connect_device(nodetree: bool = True) → None¶

Connects the device to the data server and initializes the AWGs.

Keyword Arguments: nodetree (bool) – A flag that specifies if all the parameters from the device’s nodetree should be added to the object’s attributes as zhinst-toolkit Parameters. (default: True)

AWGCore for the HDAWG¶

class zhinst.toolkit.control.drivers.hdawg.AWG(parent: zhinst.toolkit.control.drivers.base.base.BaseInstrument, index: int)¶

Bases: zhinst.toolkit.control.drivers.base.awg.AWGCore

Device-specific AWG Core for HDAWG.

This class inherits from the base AWGCore and adds zhinst-toolkit Parameters such as ouput, modulation frequency or gains. It also applies sequence specific settings for the HDAWG, depending on the type of SequenceProgram on the AWG Core.

>>> hd.awgs[0]
<zhinst.toolkit.hdawg.AWG object at 0x0000021E467D3320>
    parent  : <zhinst.toolkit.hdawg.HDAWG object at 0x0000021E467D3198>
    index   : 0
    sequence:
            type: None
            ('target', 'hdawg')
            ('clock_rate', 2400000000.0)
            ('period', 0.0001)
            ('trigger_mode', 'None')
            ('repetitions', 1)
            ('alignment', 'End with Trigger')
            ...

>>> hd.awgs[0].outputs("on")
>>> hd.awgs[0].enable_iq_modulation()
>>> hd.awgs[0].modulation_freq(123.45e6)
>>> hd.awgs[0].gain1()
1.0

See more about AWG Cores at zhinst.toolkit.control.drivers.base.AWGCore.

output1¶

State of the output 1, i.e. one of {‘on’, ‘off’}.

Type: Parameter

output2¶

State of the output 2, i.e. one of {‘on’, ‘off’}.

Type: Parameter

modulation_freq¶

Frequency of the modulation in Hz if IQ modulation is enabled.

Type: Parameter

modulation_phase_shift¶

Phase shift in degrees between I and Q quadratures if IQ modulation is enabled (default: 90).

Type: Parameter

gain1¶

Gain of the output channel 1 if IQ modulation is enabled. Must be between -1 and +1 (default: +1).

Type: Parameter

gain2¶

Gain of the output channel 2 if IQ modulation is enabled. Must be between -1 and +1 (default: +1).

Type: Parameter

disable_iq_modulation() → None¶

Disables IQ modulation on the AWG Core.

Resets the settings of the sine generators and the AWG modulation.

enable_iq_modulation() → None¶

Enables IQ Modulation on the AWG Core.

This method applies the corresponding settings for IQ modulation using one of the internal oscillators and two sine generators. The sines are used to modulate the AWG output channels. The parameters modulation_freq, modulation_phase_shift and gain1, gain2 correspond to the settings of the oscillator and the sine generators.

outputs(value=None)¶

Sets both signal outputs simultaneously.

Keyword Arguments: value (tuple) – Tuple of values {‘on’, ‘off’} for channel 1 and 2 (default: None).
Returns: A tuple with the states {‘on’, ‘off’} for the two output channels if the keyword argument is not given.

UHFQA¶

class zhinst.toolkit.UHFQA(name: str, serial: str, **kwargs)¶

Bases: zhinst.toolkit.control.drivers.base.base.BaseInstrument

High-level driver for the Zurich Instruments UHFQA Quantum Analyzer.

Inherits from BaseInstrument and adds an AWGCore and a list of ReadoutChannels. They can be accessed as properties of the UHFQA.

>>> import zhinst.toolkit as tk
>>> ...
>>> uhfqa = tk.UHFQA("uhfqa", "dev1111")
>>> uhfqa.setup()
>>> uhfqa.connect_device()
>>> ...
>>> uhfqa.nodetree
<zhinst.toolkit.tools.node_tree.NodeTree object at 0x0000021091FFC898>
nodes:
- stats
- osc
- triggers
- status
- dio
- auxin
- scope
- system
- sigins
- sigouts
- features
- auxouts
- awg
- qa
parameters:
- clockbase

A measurement using the AWG Core could look like this:

>>> uhfqa.awg.set_sequence_params(...)
>>> uhfqa.channels[0].enable()
>>> uhfqa.channels[0].readout_frequency(123e6)
>>> ...
>>> uhfqa.arm(length=100, averages=1)   # arm the QA Readout, set length and averages
>>> uhfqa.awg.run()                     # start the AWG
>>> uhfqa.awg.wait_done()               # wait until AWG is finished
>>> result = uhfqa.channels[0].result() # get the result vector

Parameters

name (str) – Identifier for the UHFQA.
serial (str) – Serial number of the device, e.g. ‘dev1234’. The serial number can be found on the back panel of the instrument.

awg¶

A device-specific AWGCore for the UHFQA.

Type: zhinst.toolkit.control.drivers.uhfqa.AWG

channels¶

A list of ten zhinst.toolkit.control.drivers.uhfqa.ReadoutChannel s that each represent the digital signal processing path on the instrument.

Type: list

integration_time¶

The time in seconds used for signal integration. The value must be positive. The maximum value when using weighted integration is 4096 samples or ca. 2.275 us (default: 2.0 us).

Type: zhinst.toolkit.control.node_tree.Parameter

result_source¶

This parameter selects the stage in the signal processing path that is used as the source for the QA results. It can be one of {“Crosstalk”, “Threshold”, “Rotation”, “Crosstalk Correlation”, “Threshold Correlation”, “Integration”}.

Type: zhinst.toolkit.control.node_tree.Parameter

averaging_mode¶

Mode of averaing in the QA Result Acquisition. Either “Sequential” or “Cyclic”. “Sequential”: The first point of the Result vector is the average of the first N results where N is the value of the result averages setting. The second point is the average of the next N results, and so forth. “Cyclic”: The first point in the Result vector is the average of the results 1, M+1, 2M+1, …, where M is the value of the result length setting. The second point is the average of the results number 2, M+2, 2M+2, …, and so forth.

Type: zhinst.toolkit.control.node_tree.Parameter

arm(length=None, averages=None) → None¶

Prepare UHFQA for result acquisition.

This method enables the QA Results Acquisition and resets the acquired points. Optionally, the result length and result averages can be set when specified as keyword arguments. If they are not specified, they are not changed.

Keyword Arguments

length (int) – If specified, the length of the result vector will be set before arming the UHFQA readout. (default: None)
averages (int) – If specified, the result averages will be set before arming the UHFQA readout. (default: None)

connect_device(nodetree: bool = True) → None¶

Connects the device to the data server and initializes the AWG.

Keyword Arguments: nodetree (bool) – A flag that specifies if all the parameters from the device’s nodetree should be added to the object’s attributes as zhinst-toolkit Parameters. (default: True)

crosstalk_matrix(matrix=None)¶

Sets or gets the crosstalk matrix of the UHFQA as a 2D array.

Keyword Arguments: matrix (2D array) – The 2D matrix used in the digital signal processing path to compensate for crosstalk between the different channels. The given matrix can also be a part of the entire 10 x 10 matrix. Its maximum dimensions are 10 x 10. (default: None)
Returns: If no argument is given the method returns the current crosstalk matrix as a 2D numpy array.

disable_readout_channels(channels: List = range(0, 10)) → None¶

Disables weighted integration on the specified readout channels.

Keyword Arguments: channels (list) – A list of indices of channels to disable. (default: range(10))

enable_readout_channels(channels: List = range(0, 10)) → None¶

Enables weighted integration on the specified readout channels.

Keyword Arguments: channels (list) – A list of indices of channels to enable. (default: range(10))

AWGCore for the UHFQA¶

class zhinst.toolkit.control.drivers.uhfqa.AWG(parent: zhinst.toolkit.control.drivers.base.base.BaseInstrument, index: int)¶

Bases: zhinst.toolkit.control.drivers.base.awg.AWGCore

Device-specific AWG Core for UHFQA.

Inherits from AWGCore and adds zhinst-toolkit Parameters like ouput or gains. This class also specifies sequence specific settings for the UHFQA.

output1¶

The state of the output of channel 1. Can be one of {‘on’, ‘off’}.

Type: zhinst.toolkit.control.node_tree.Parameter

output2¶

The state of the output of channel 2. Can be one of {‘on’, ‘off’}.

Type: zhinst.toolkit.control.node_tree.Parameter

gain1¶

Gain of the output channel 1. The value must be between -1 and +1 (default: +1).

Type: zhinst.toolkit.control.node_tree.Parameter

gain2¶

Gain of the output channel 2. The value must be between -1 and +1 (default: +1).

Type: zhinst.toolkit.control.node_tree.Parameter

compile() → None¶: Wraps the ‘compile(…)’ method of the parent class AWGCore.

outputs(value=None)¶

Sets both signal outputs simultaneously.

Keyword Arguments: value (tuple) – Tuple of values {‘on’, ‘off’} for channel 1 and 2 (default: {None})
Returns: The state {‘on’, ‘off’} for both outputs if the keyword argument is not given.

update_readout_params() → None¶: Updates the sequence parameters for ‘Simple’ sequence with values from the readout channels.

Readout Channel¶

class zhinst.toolkit.control.drivers.uhfqa.ReadoutChannel(parent: zhinst.toolkit.control.drivers.base.base.BaseInstrument, index: int)¶

Bases: object

Implements a Readout Channel for UHFQA.

This class represents the signal processing chain for one of the ten ReadoutChannels of a UHFQA. One channel is typically used for dispersive resonator readout of superconducting qubits.

>>> ch = uhfqa.channels[0]
>>> uhfqa.result_source("Threshold")
>>> ...
>>> ch.enable()
>>> ch.readout_frequency(85.6e6)
>>> ch
Readout Channel 0:  <zhinst.toolkit.uhfqa.ReadoutChannel object at 0x0000021091FD4F28>
    rotation          : 0.0
    threshold         : 0.0
    readout_frequency : 85600000.0
    readout_amplitude : 1
    phase_shift       : 0
>>> ch.rotation(123.4)
>>> ch.threshold(-56.78)
>>> ...
>>> ch.result()
array([0.0, 1.0, 1.0, 1.0, 0.0, ...])

The readout channel can be enabled with enable() which means that the weighted integration mode is activated and integration weights are set to demodulate the signal at the given readout frequency. If the channel is enabled, the readout parameters are also used for signal generation in the AWGCore if the sequence type is set to ‘Readout’.

index¶

The index of the Readout Channel from 1 - 10.

Type: int

rotation¶

The rotation applied to the signal in IQ plane. The angle is specified in degrees.

Type: zhinst.toolkit.control.nodetree.Parameter

threshold¶

The signal threshold used for state discrimination in the thresholding unit.

Type: zhinst.toolkit.control.nodetree.Parameter

result¶

This read-only Parameter holds the result vector for the given readout channel as a 1D numpy array.

Type: zhinst.toolkit.control.nodetree.Parameter

disable() → None¶: Disables weighted integration for this channel.

enable() → None¶: Enables weighted integration for this channel.

enabled() → bool¶: Returns if weighted integration is enabled.

phase_shift(ph=None)¶

Sets or gets the readout phase shift for this channel.

Additional phase shift in the signal generation between I and Q quadtratures. (default: 0)

readout_amplitude(amp=None)¶

Sets or gets the readout amplitude for this channel.

The amplitude of the readout pulse is used for signal generation of the readout tone if the channel is enabled and if the AWG SequenceProgram is of type ‘Readout’. (default: 1.0)

readout_frequency(freq=None)¶

Sets or gets the readout frequency for this channel.

Readout frequency in Hz of the readout channel. If the AWG SequenceProgram is of type “Readout”, this Parameter is used to generate a readout tone at the given readout frequency for all readout channels that are enabled. This frequency is also used in the signal acquisition for digital demodulation if the readout channel is enabled. The frequency must be positive.

PQSC¶

class zhinst.toolkit.PQSC(name: str, serial: str, **kwargs)¶

Bases: zhinst.toolkit.control.drivers.base.base.BaseInstrument

High-level driver for the Zurich Instruments PQSC.

>>> import zhinst.toolkit as tk
>>> pqsc = tk.PQSC("pqsc", "dev1234")
>>> pqsc.setup()
>>> pqsc.connect_device()
>>> pqsc.nodetree
>>> ...

Parameters

name (str) – Identifier for the PQSC.
serial (str) – Serial number of the device, e.g. ‘dev1234’. The serial number can be found on the back panel of the instrument.

UHFLI¶

class zhinst.toolkit.UHFLI(name: str, serial: str, **kwargs)¶

Bases: zhinst.toolkit.control.drivers.base.base.BaseInstrument

High-level driver for Zurich Instruments UHFLI Lock-In Amplifier.

Inherits from BaseInstrument and adds a DAQModule, a SweeperModule and an AWGCore (if option installed). The modules can be accessed as properties of the UHFLI.

>>> import zhinst.toolkit as tk
>>> uhfli = tk.UHFLI("uhfli", "dev1111")
>>> uhfli.setup()
>>> uhfli.connect_device()
>>> uhfli.nodetree
>>> ...

>>> signal = uhfli.daq.signals_add("demod1", "r")
>>> uhfli.daq.measure()
...
>>> result = uhfli.daq.results[signal]

>>> signal = uhfli.sweeper.signals_add("demod1")
>>> uhfli.sweeper.sweep_parameter("frequency")
>>> uhfli.sweeper.measure()
...
>>> result = uhfli.sweeper.results[signal]

name¶

Identifier for the UHFLI.

Type: str

serial¶

Serial number of the device, e.g. ‘dev1234’. The serial number can be found on the back panel of the instrument.

Type: str

daq¶

Data Acquisition Module of the instrument.

Type: zhinst.toolkit.control.drivers.base.DAQModule

sweeper¶

Sweeper Module of the instrument.

Type: zhinst.toolkit.control.drivers.base.SweeperModule

awg¶

AWG Module of the instrument if the the option is installed.

Type: zhinst.toolkit.control.drivers.uhfqa.AWG

connect_device(nodetree: bool = True) → None¶

Establishes a device connection.

Connects the device to a data server and initializes the DAQModule, SweeperModule and AWG (if option installed).

Keyword Arguments: nodetree (bool) – A flag that specifies if all the parameters from the device’s nodetree should be added to the object’s attributes as zhinst-toolkit Parameters. (default: True)

MFLI¶

class zhinst.toolkit.MFLI(name: str, serial: str, **kwargs)¶

Bases: zhinst.toolkit.control.drivers.base.base.BaseInstrument

High-level driver for the Zurich Instruments MFLI Lock-In Amplifier.

Inherits from BaseInstrument and adds a DAQModule and a SweeperModule. They can be accessed as properties of the MFLI.

>>> import zhinst.toolkit as tk
>>> mfli = tk.MFLI("mfli", "dev1234")
>>> mfli.setup()
>>> mfli.connect_device()
>>> mfli.nodetree
...

>>> signal = mfli.daq.signals_add("demod1", "r")
>>> mfli.daq.measure()
...
>>> result = mfli.daq.results[signal]

>>> signal = mfli.sweeper.signals_add("demod1")
>>> mfli.sweeper.sweep_parameter("frequency")
>>> mfli.sweeper.measure()
...
>>> result = mfli.sweeper.results[signal]

name¶

Identifier for the MFLI.

Type: str

serial¶

Serial number of the device, e.g. ‘dev1234’. The serial number can be found on the back panel of the instrument.

Type: str

daq¶

Data Acquisition Module of the instrument.

Type: zhinst.toolkit.control.drivers.base.DAQModule

sweeper¶

Sweeper Module of the instrument.

Type: zhinst.toolkit.control.drivers.base.SweeperModule

connect_device(nodetree: bool = True) → None¶

Establishes the device connection.

Connects the device to the data server and initializes the DAQ Module and Sweeper Module.

Keyword Arguments: nodetree (bool) – A flag that specifies if all the parameters from the nodetree should be added to the object’s attributes as zhinst-toolkit Parameters. (default: True)