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 |
ziDAQServer
|
A core API session. |
required |
node |
str
|
path of the node that should change to expected value |
required |
expected_value |
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 |
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 |
ziDAQServer
|
An instance of the core.ziDAQServer class (representing an API session connected to a Data Server). |
required |
exclude |
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)
¶
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 |
ndarray
|
a 1-dimensional array containing demodulator timestamps |
required |
Returns:
Type | Description |
---|---|
ndarray
|
A 1-dimensional array indicating the indices in timestamp where |
ndarray
|
sampleloss has occurred. An empty array is returned in no sampleloss was |
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 |
ndarray
|
Array with data of waveform 1. |
required |
wave2 |
Optional[ndarray]
|
Array with data of waveform 2. |
None
|
markers |
Optional[ndarray]
|
Array with marker data. |
None
|
Returns:
Type | Description |
---|---|
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 |
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 |
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 |
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 |
ziDAQServer
|
An instance of the core.ziDAQServer class (representing an API session connected to a Data Server). |
required |
Returns:
Type | Description |
---|---|
List[str]
|
A list of strings of connected device IDs. The list is empty if no devices |
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 |
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 |
---|---|
List[Tuple[str, int]]
|
A list of lists as provided to ziDAQServer's set() |
List[Tuple[str, int]]
|
command. Each sub-list forms a nodepath, value pair. This is a list of |
List[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 |
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 |
---|---|
ndarray
|
A numpy structured array of shape (num_points,) whose field names |
ndarray
|
correspond to the column names in the first line of the CSV file. |
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 |
Union[str, Path]
|
The file or filename of the CSV file to load. |
required |
column_names |
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 |
ndarray
|
A numpy structured array of shape (num_points,) |
ndarray
|
whose field names correspond to the column names in the first line of the |
|
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 |
---|---|
Dict
|
A nested dictionary containing the instrument data as |
Dict
|
specified in the LabOne User Interface. The nested structure of |
Dict
|
corresponds to the path of the data's node in the instrument's node |
Dict
|
hierarchy. |
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 |
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 |
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 |
ndarray
|
A numpy structured array of shape (num_points,) |
ndarray
|
whose field names correspond to the field names of a ziControl demodulator |
|
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 |
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 |
---|---|
ndarray
|
A numpy structured array of shape (num_points,) whose field names |
ndarray
|
correspond to the field names of a ziControl demodulator sample. |
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 |
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 |
---|---|
ndarray
|
Three separated arrays are returned. The waveforms are scaled to be in the |
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 |
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 |
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 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 |
Union[float, List[float]]
|
The RMS voltage to be converted |
required |
input_impedance_ohm |
int
|
The input impedance in Ohm |
50
|
Returns:
Type | Description |
---|---|
Union[float, 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 |
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. |
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