Skip to content

Python Utils

utils

Zurich Instruments LabOne Python API Utility Functions.

This module provides basic utility functions to ease the use of the native Python API zhinst-core.

LABONE_DEMOD_DTYPE = list(zip(LABONE_DEMOD_NAMES, LABONE_DEMOD_FORMATS)) module-attribute

LABONE_DEMOD_FORMATS = ('u8', 'u8', 'f8', 'f8', 'f8', 'f8', 'u4', 'u4', 'f8', 'f8') module-attribute

LABONE_DEMOD_NAMES = ('chunk', 'timestamp', 'x', 'y', 'freq', 'phase', 'dio', 'trigger', 'auxin0', 'auxin1') module-attribute

ZICONTROL_DTYPE = list(zip(ZICONTROL_NAMES, ZICONTROL_FORMATS)) module-attribute

ZICONTROL_FORMATS = ('f8', 'f8', 'f8', 'f8', 'u4', 'f8', 'f8') module-attribute

ZICONTROL_NAMES = ('t', 'x', 'y', 'freq', 'dio', 'auxin0', 'auxin1') module-attribute

api_server_version_check(daq)

Check the consistency of the used version in the LabOne stack.

Issue a warning and return False if the release version of the API used in the session (daq) does not have the same release version as the Data Server (that the API is connected to). If the versions match return True.

Parameters:

Name Type Description Default
daq ziDAQServer

An instance of the core.ziDAQServer class (representing an API session connected to a Data Server).

required

Returns:

Type Description
bool

Flag if the Versions of API and Data Server match.

Raises:

Type Description
Warning

If the Versions of API and Data Server do not match.

assert_node_changes_to_expected_value(daq, node, expected_value, sleep_time=0.005, max_repetitions=200)

Polls a node until it has the the expected value.

If the node didn't change to the expected value within the maximum number of polls an assertion error is issued.

Parameters:

Name Type Description Default
daq zi.ziDAQServer

A core API session.

required
node str

path of the node that should change to expected value

required
expected_value t.Union[int, float, str]

value the node is expected to change to

required
sleep_time float

time in seconds to wait between requesting th value

0.005
max_repetitions int

max. number of loops we wait for the node to change

200

Raises:

Type Description
AssertionError

If the node doesn't change to the expected value within the given time.

autoConnect(default_port=None, api_level=None)

Try to connect to a Zurich Instruments Data Server (UHF,HF2 only).

Important: autoConnect() does not support MFLI devices.

Parameters:

Name Type Description Default
default_port int

The default port to use when connecting to the Data Server (specify 8005 for the HF2 Data Server and 8004 for the UHF Data Server) If default_port is not specified (=None) then first try to connect to a HF2, if no server devices are found then try to connect to an UHF. This behaviour is useful for the API examples. If we cannot connect to a server and/or detect a connected device raise a RuntimeError. (default=None).

None
api_level int

The API level to use, either 1, 4 or 5. HF2 only supports Level 1, Level 5 is recommended for UHF and MFLI devices (default=None).

None

Returns:

Name Type Description
ziDAQServer zi.ziDAQServer

An instance of the core.ziDAQServer class that is used for communication to the Data Server.

Raises:

Type Description
RuntimeError

If no running Data Server is found or no device is found that is attached to a Data Server.x

autoDetect(daq, exclude=None)

Return one of the devices connected to the Data Server.

Return a string containing the first device ID (not in the exclude list) that is attached to the Data Server connected via daq, an instance of the core.ziDAQServer class.

Parameters:

Name Type Description Default
daq zi.ziDAQServer

An instance of the core.ziDAQServer class (representing an API session connected to a Data Server).

required
exclude t.List[str]

A list of strings specifying devices to exclude. autoDetect() will not return the name of a device in this list.

None

Returns:

Type Description
str

Device ID of a device connected to the Data Server not in exclude.

Raises:

Type Description
RuntimeError

If no device was found.

RuntimeError

If daq is not an instance of core.ziDAQServer.

Example:

import zhinst.utils
daq = zhinst.utils.autoConnect()
device = zhinst.utils.autoDetect(daq)

bw2tc(bandwidth, order)

Convert the demodulator 3 dB bandwidth to its equivalent timeconstant.

Parameters:

Name Type Description Default
bandwidth float

The demodulator 3dB bandwidth to convert.

required
order int

The demodulator order (1 to 8) for which to convert the bandwidth.

required

Returns:

Type Description
float

The equivalent demodulator timeconstant.

bwtc_scaling_factor(order)

Return the appropriate scaling factor for bandwidth to timeconstant.

Conversion for the provided demodulator order.

Parameters:

Name Type Description Default
order int

demodulator order.

required

Returns:

Type Description
float

Scaling factor for the bandwidth to timeconstant.

check_for_sampleloss(timestamps)

Check for sample loss.

Check whether timestamps are equidistantly spaced, it not, it is an indication that sampleloss has occurred whilst recording the demodulator data.

This function assumes that the timestamps originate from continuously saved demodulator data, during which the demodulator sampling rate was not changed.

Parameters:

Name Type Description Default
timestamps np.ndarray

a 1-dimensional array containing demodulator timestamps

required

Returns:

Type Description
np.ndarray

A 1-dimensional array indicating the indices in timestamp where

np.ndarray

sampleloss has occurred. An empty array is returned in no sampleloss was

np.ndarray

present.

convert_awg_waveform(wave1, wave2=None, markers=None)

Convert one or multiple waveforms into the native AWG waveform format.

Converts one or multiple arrays with waveform data to the native AWG waveform format (interleaved waves and markers as uint16).

Waveform data can be provided as integer (no conversion) or floating point (range -1 to 1) arrays.

Parameters:

Name Type Description Default
wave1 np.ndarray

Array with data of waveform 1.

required
wave2 t.Optional[np.ndarray]

Array with data of waveform 2.

None
markers t.Optional[np.ndarray]

Array with marker data.

None

Returns:

Type Description
np.ndarray

The converted uint16 waveform is returned.

create_api_session(device_serial, api_level, server_host=None, server_port=8004, *, required_devtype=None, required_options=None, required_err_msg=None)

Create an API session for the specified device.

Parameters:

Name Type Description Default
device_serial str

A string specifying the device serial number. For example, 'uhf-dev2123' or 'dev2123'.

required
api_level int

The targeted API level used by the code where the returned API session will be used. The maximum API level you may use is defined by the device class. HF2 only supports API level 1 and other devices support API level 6. You should try to use the maximum level possible to enable extended API features.

required
server_host str

A hostname or IP address. The data server can be omitted if the targeted device is an MF* device or a local data server is running. In this case it will try to connect to the local data server or device internal data server (local server has priority).

None
server_port int

The port number of the data server. The default port is 8004.

8004
required_devtype str

Deprecated: This option will be ignored.

None
required_options str

Deprecated: This option will be ignored.

None
required_err_msg str

Deprecated: This option will be ignored.

None

Returns:

Name Type Description
daq zi.ziDAQServer

An instance of the core.ziDAQServer class (representing an API session connected to a Data Server).

device str

The device's ID, this is the string that specifies the device's node branch in the data server's node tree.

props t.Dict

The device's discovery properties as returned by the ziDiscovery get() method.

default_output_mixer_channel(discovery_props, output_channel=0)

Return an instrument's default output mixer channel.

Based on the specified devicetype and options discovery properties and the hardware output channel.

This utility function is used by the core examples and returns a node available under the /devX/sigouts/0/{amplitudes,enables}/ branches.

Parameters:

Name Type Description Default
discovery_props t.Dict

A device's discovery properties as returned by ziDiscovery's get() method.

required
output_channel int

The zero-based index of the hardware output channel for which to return an output mixer channel.

0

Returns:

Type Description
int

The zero-based index of an available signal output mixer channel.

Raises:

Type Description
Exception

If an invalid signal input index was provided.

devices(daq)

List of device_id of all devices connected to the Data Server.

Return a list of strings containing the device IDs that are attached to the Data Server connected via daq, an instance of the core.ziDAQServer class. Returns an empty list if no devices are found.

Parameters:

Name Type Description Default
daq zi.ziDAQServer

An instance of the core.ziDAQServer class (representing an API session connected to a Data Server).

required

Returns:

Type Description
t.List[str]

A list of strings of connected device IDs. The list is empty if no devices

t.List[str]

are detected.

Raises:

Type Description
RuntimeError

If daq is not an instance of core.ziDAQServer.

Example:

import zhinst.utils
daq = zhinst.utils.autoConnect()  # autoConnect not supported for MFLI devices
device = zhinst.utils.autoDetect(daq)

disable_everything(daq, device)

Put the device in a known base configuration.

disable all extended functionality; disable all streaming nodes.

Parameters:

Name Type Description Default
daq zi.ziDAQServer

An instance of the core.ziDAQServer class (representing an API session connected to a Data Server).

required
device str

The device ID specifying where to load the settings, e.g., 'dev123'.

required

Returns:

Type Description
t.List[t.Tuple[str, int]]

A list of lists as provided to ziDAQServer's set()

t.List[t.Tuple[str, int]]

command. Each sub-list forms a nodepath, value pair. This is a list of

t.List[t.Tuple[str, int]]

nodes configured by the function and may be reused.

Warning

This function is intended as a helper function for the API's examples and it's signature or implementation may change in future releases.

get_default_settings_path(daq)

Return the default path used for settings by the ziDeviceSettings module.

Parameters:

Name Type Description Default
daq zi.ziDAQServer

A core API session.

required

Returns:

Name Type Description
settings_path str

The default ziDeviceSettings path.

load_labone_csv(fname)

Load a csv file generated from LabOne.

Load a CSV file containing generic data as saved by the LabOne User Interface into a numpy structured array.

Parameters:

Name Type Description Default
fname str

The filename of the CSV file to load.

required

Returns:

Type Description
np.ndarray

A numpy structured array of shape (num_points,) whose field names

np.ndarray

correspond to the column names in the first line of the CSV file.

np.ndarray

num_points is the number of lines in the CSV file - 1.

Example:

import zhinst.utils
# Load the CSV file of PID error data (node: /dev2004/pids/0/error)
data = zhinst.utils.load_labone_csv('dev2004_pids_0_error_00000.csv')
import matplotlib.pyplot as plt
# Plot the error
plt.plot(data['timestamp'], data['value'])

load_labone_demod_csv(fname, column_names=LABONE_DEMOD_NAMES)

Load a CSV file containing demodulator samples.

Load a CSV file containing demodulator samples as saved by the LabOne User Interface into a numpy structured array.

Parameters:

Name Type Description Default
fname t.Union[str, Path]

The file or filename of the CSV file to load.

required
column_names t.List[str]

A list (or tuple) of column names to load from the CSV file. Default is to load all columns.

LABONE_DEMOD_NAMES

Returns:

Name Type Description
sample np.ndarray

A numpy structured array of shape (num_points,)

np.ndarray

whose field names correspond to the column names in the first line of the

np.ndarray

CSV file. num_points is the number of lines in the CSV file - 1.

Example:

import zhinst.utils
sample = zhinst.utils.load_labone_demod_csv(
  'dev2004_demods_0_sample_00000.csv',
  ('timestamp', 'x', 'y'))
import matplotlib.pyplot as plt
import numpy as np
plt.plot(sample['timestamp'], np.abs(sample['x'] + 1j*sample['y']))

load_labone_mat(filename)

Load a mat file generated from LabOne.

A wrapper function for loading a MAT file as saved by the LabOne User Interface with scipy.io's loadmat() function. This function is included mainly to document how to work with the data structure return by scipy.io.loadmat().

Parameters:

Name Type Description Default
filename str

the name of the MAT file to load.

required

Returns:

Type Description
t.Dict

A nested dictionary containing the instrument data as

t.Dict

specified in the LabOne User Interface. The nested structure of data

t.Dict

corresponds to the path of the data's node in the instrument's node

t.Dict

hierarchy.

Further comments

The MAT file saved by the LabOne User Interface (UI) is a Matlab V5.0 data file. The LabOne UI saves the specified data using native Matlab data structures in the same format as are returned by commands in the LabOne Matlab API. More specifically, these data structures are nested Matlab structs, the nested structure of which correspond to the location of the data in the instrument's node hierarchy.

Matlab structs are returned by scipy.io.loadmat() as dictionaries, the name of the struct becomes a key in the dictionary. However, as for all objects in MATLAB, structs are in fact arrays of structs, where a single struct is an array of shape (1, 1). This means that each (nested) dictionary that is returned (corresponding to a node in node hierarchy) is loaded by scipy.io.loadmat as a 1-by-1 array and must be indexed as such. See the Example section below.

For more information please refer to the following link: http://docs.scipy.org/doc/scipy/reference/tutorial/io.html#matlab-structs

Example:

device = 'dev88'
# See ``Further explanation`` above for a comment on the indexing:
timestamp = data[device][0,0]['demods'][0,0]['sample'][0,0]['timestamp'][0]
x = data[device][0,0]['demods'][0,0]['sample'][0,0]['x'][0]
y = data[device][0,0]['demods'][0,0]['sample'][0,0]['y'][0]
import matplotlib.pyplot as plt
import numpy as np
plt.plot(timestamp, np.abs(x + 1j*y))
# If multiple demodulator's are saved, data from the second demodulator,
# e.g., is accessed as following:
x = data[device][0,0]['demods'][0,1]['sample'][0,0]['x'][0]

load_settings(daq, device, filename)

Load a LabOne settings file to the specified device.

This function is synchronous; it will block until loading the settings has finished.

Parameters:

Name Type Description Default
daq zi.ziDAQServer

A core API session.

required
device str

The device ID specifying where to load the settings, e.g., 'dev123'.

required
filename str

The filename of the xml settings file to load. The filename can include a relative or full path.

required

Raises:

Type Description
RuntimeError

If loading the settings times out.

Examples:

import zhinst.utils as utils
daq = utils.autoConnect()
dev = utils.autoDetect(daq)
# Then, e.g., load settings from a file in the current directory:
utils.load_settings(daq, dev, 'my_settings.xml')
# Then, e.g., load settings from the default LabOne settings path:
filename = 'default_ui.xml'
path = utils.get_default_settings_path(daq)
utils.load_settings(daq, dev, path + os.sep + filename)

load_zicontrol_csv(filename, column_names=ZICONTROL_NAMES)

Load a CSV file containing demodulator samples.

Load a CSV file containing demodulator samples as saved by the ziControl User Interface into a numpy structured array.

Parameters:

Name Type Description Default
filename str

The file or filename of the CSV file to load.

required
column_names t.List[str]

A list (or tuple) of column names (demodulator sample field names) to load from the CSV file. Default is to load all columns.

ZICONTROL_NAMES

Returns:

Name Type Description
sample np.ndarray

A numpy structured array of shape (num_points,)

np.ndarray

whose field names correspond to the field names of a ziControl demodulator

np.ndarray

sample. num_points is the number of lines in the CSV file - 1.

Example:

import zhinst.utils
import matplotlib.plt as plt
import numpy as np
sample = zhinst.utils.load_labone_csv('Freq1.csv', ('t', 'x', 'y'))
plt.plot(sample['t'], np.abs(sample['x'] + 1j*sample['y']))

load_zicontrol_zibin(filename, column_names=ZICONTROL_NAMES)

Load a ziBin file containing demodulator samples.

Load a ziBin file containing demodulator samples as saved by the ziControl User Interface into a numpy structured array. This is for data saved by ziControl in binary format.

Note

Specifying a fewer names in column_names will not result in a speed-up as all data is loaded from the binary file by default.

Parameters:

Name Type Description Default
filename str

The filename of the .ziBin file to load.

required
column_names t.List[str]

A list (or tuple) of column names to load from the CSV file. Default is to load all columns.

ZICONTROL_NAMES

Returns:

Type Description
np.ndarray

A numpy structured array of shape (num_points,) whose field names

np.ndarray

correspond to the field names of a ziControl demodulator sample.

np.ndarray

num_points is the number of sample points saved in the file.

Example:

import zhinst.utils
sample = zhinst.utils.load_zicontrol_zibin('Freq1.ziBin')
import matplotlib.plt as plt
import numpy as np
plt.plot(sample['t'], np.abs(sample['x'] + 1j*sample['y']))

parse_awg_waveform(wave_uint, channels=1, markers_present=False)

Convert a native AWG waveform into the individual waves.

Converts a received waveform from the AWG waveform node into floating point and separates its contents into the respective waves (2 waveform waves and 1 marker wave), depending on the input.

Parameters:

Name Type Description Default
wave_uint np.ndarray

A uint16 array from the AWG waveform node.

required
channels int

Number of channels present in the wave.

1
markers_present bool

Indicates if markers are interleaved in the wave.

False

Returns:

Type Description
np.ndarray

Three separated arrays are returned. The waveforms are scaled to be in the

np.ndarray

range [-1 and 1]. If no data is present the respective array is empty.

save_settings(daq, device, filename)

Save settings from the specified device to a LabOne settings file.

This function is synchronous; it will block until saving the settings has finished.

Parameters:

Name Type Description Default
daq zi.ziDAQServer

A core API session.

required
device str

The device ID specifying where to load the settings, e.g., 'dev123'.

required
filename str

The filename of the LabOne xml settings file. The filename can include a relative or full path.

required

Raises:

Type Description
RuntimeError

If saving the settings times out.

Examples:

import zhinst.utils as utils
daq = utils.autoConnect()
dev = utils.autoDetect(daq)

# Then, e.g., save settings to a file in the current directory:
utils.save_settings(daq, dev, 'my_settings.xml')

# Then, e.g., save settings to the default LabOne settings path:
filename = 'my_settings_example.xml'
path = utils.get_default_settings_path(daq)
utils.save_settings(daq, dev, path + os.sep + filename)

sigin_autorange(daq, device, in_channel)

Perform an automatic adjustment of the signal input range.

Based on the measured input signal. This utility function starts the functionality implemented in the device's firmware and waits until it has completed. The range is set by the firmware based on the measured input signal's amplitude measured over approximately 100 ms.

Requirements

A devtype that supports autorange functionality on the firmware level, e.g., UHFLI, MFLI, MFIA.

Parameters:

Name Type Description Default
daq zi.ziDAQServer

A core API session.

required
device str

The device ID on which to perform the signal input autorange.

required
in_channel int

The index of the signal input channel to autorange.

required

Returns:

Type Description
float

Signal input range.

Raises:

Type Description
AssertionError

If the functionality is not supported by the device or an invalid in_channel was specified.

RuntimeError

If autorange functionality does not complete within the timeout.

Example:

import zhinst.utils
device_serial = 'dev2006'
(daq, _, _) = zhinst.utils.create_api_session(device_serial, 5)
input_channel = 0
zhinst.utils.sigin_autorange(daq, device_serial, input_channel)

systemtime_to_datetime(systemtime)

Convert the LabOne "systemtime" into a datetime object.

Convert the LabOne "systemtime" returned in LabOne data headers from microseconds since Unix epoch to a datetime object with microsecond precision.

Parameters:

Name Type Description Default
systemtime int

Labone "systemtime" returned by LabOne.

required

Returns:

Type Description
datetime.datetime

datetime object.

tc2bw(timeconstant, order)

Convert the demodulator timeconstant to its equivalent 3 dB bandwidth.

Parameters:

Name Type Description Default
timeconstant float

The equivalent demodulator timeconstant.

required
order int

The demodulator order (1 to 8) for which to convert the bandwidth.

required

Returns:

Type Description
float

The demodulator 3dB bandwidth to convert.

volt_rms_to_dbm(volt_rms, input_impedance_ohm=50)

Converts a Root Mean Square (RMS) voltage into a dBm power value.

Parameters:

Name Type Description Default
volt_rms t.Union[float, t.List[float]]

The RMS voltage to be converted

required
input_impedance_ohm int

The input impedance in Ohm

50

Returns:

Type Description
t.Union[float, t.List[float]]

The power in dBm corresponding to the volt_rms argument is returned.

wait_for_state_change(daq, node, value, timeout=1.0, sleep_time=0.005)

Waits until a node has the expected state/value.

Attention: Only supports integer values as reference.

Parameters:

Name Type Description Default
daq zi.ziDAQServer

A core API session.

required
node str

Path of the node.

required
value int

expected value.

required
timeout float

max in seconds. (default = 1.0)

1.0
sleep_time float

sleep interval in seconds. (default = 0.005)

0.005

Raises:

Type Description
TimeoutError

If the node did not changed to the expected value within the given time.