Skip to content

Python Utils SHFQA

zhinst.utils.shfqa

Zurich Instruments LabOne Python API Utility functions for SHFQA.

SHFQA_MAX_SIGNAL_GENERATOR_CARRIER_COUNT = 16 module-attribute

SHFQA_MAX_SIGNAL_GENERATOR_WAVEFORM_LENGTH = 4 * 2 ** 10 module-attribute

SHFQA_SAMPLING_FREQUENCY = 2000000000.0 module-attribute

configure_channel = configure_maker(get_channel_settings, partial(build_docstring_configure, new_first_line='Configures the RF input and output of a specified channel.')) module-attribute

configure_result_logger_for_readout = configure_maker(get_result_logger_for_readout_settings, partial(build_docstring_configure, 'Configures a specified result logger for readout mode.')) module-attribute

configure_result_logger_for_spectroscopy = configure_maker(get_result_logger_for_spectroscopy_settings, partial(build_docstring_configure, 'Configures a specified result logger for spectroscopy mode.')) module-attribute

configure_scope = configure_maker(get_scope_settings, partial(build_docstring_configure, new_first_line='Configures the scope for a measurement.')) module-attribute

configure_sequencer_triggering = configure_maker(get_sequencer_triggering_settings, partial(build_docstring_configure, new_first_line='Configures the triggering of a specified sequencer.')) module-attribute

configure_weighted_integration = configure_maker(get_configure_weighted_integration_settings, partial(build_docstring_configure, 'Configures the weighted integration on a specified channel.')) module-attribute

ziDAQServer(host, port, api_level, allow_version_mismatch=False)

Class to connect with a Zurich Instruments data server.

Parameters:

Name Type Description Default
host str

Host string e.g. '127.0.0.1' for localhost

 required
port int

Port number e.g. 8004 for the ziDataServer.

 required
api_level Literal[0, 1, 4, 5, 6]

API level number.

 required
allow_version_mismatch bool

if set to True, the connection to the data-server will succeed even if the data-server is on a different version of LabOne. If False, an exception will be raised if the data-server is on a different version. (default = False)

 False

api_level: Literal[0, 1, 4, 5, 6] property

The ziAPI level used for the active connection.

.. versionadded:: 22.08

host: str property

The host used for the active connection.

.. versionadded:: 22.08

port: int property

The port used for the active connection.

.. versionadded:: 22.08

asyncGetAsEvent(path)

Trigger an event on the specified node.

The node data is returned by a subsequent poll command.

The difference to the non async equivalent is that this function returns immediately, even before the data server has received the request. This gives the lowest latency at the cost of not providing feedback if the request fails

.. versionadded:: 23.02

Parameters:

Name Type Description Default
path str

Path string of the node. Note: Wildcards and paths referring to streaming nodes are not permitted.

 required

asyncSetDouble(path, value)

Asynchronously set the value as double for a specified node.

Asynchronously means that the command is nonblocking and does not wait for the data server acknowledgement.

Warning

This command does have no error reporting at all.

Parameters:

Name Type Description Default
path str

Path string of the node.

 required
value float

Value of the node.

 required

asyncSetInt(path, value)

Asynchronously set the value as integer for a specified node.

Asynchronously means that the command is nonblocking and does not wait for the data server acknowledgement.

Warning

This command does have no error reporting at all.

Parameters:

Name Type Description Default
path str

Path string of the node.

 required
value int

Value of the node.

 required

asyncSetString(path, value)

Asynchronously set the value as string for a specified node.

Asynchronously means that the command is nonblocking and does not wait for the data server acknowledgement.

Warning

This command does have no error reporting at all.

Parameters:

Name Type Description Default
path str

Path string of the node.

 required
value str

Value of the node.

 required

awgModule()

Create a AwgModule object.

This will start a thread for running an asynchronous module.

Returns:

Type Description
AwgModule

Created module instance.

connect()

Initiate the connection to the data server.

Important

During the object initialization the connection is already established. It is therefore not necessary to call this function unless one actively disconnects from the data server with the disconnect method.

connectDevice(dev, interface, params=None)

Connect with the data server to a specified device.

The device must be visible to the server. If the device is already connected the call will be ignored. The function will block until the device is connected and the device is ready to use.

Parameters:

Name Type Description Default
dev str

Device serial.

 required
interface Literal['USB', 'PCIe', '1GbE']

Device interface.

 required
params Optional[str]

Optional interface parameters string.

 None

dataAcquisitionModule()

Create a DataAcquisitionModule object.

This will start a thread for running an asynchronous module.

Returns:

Type Description
DataAcquisitionModule

Created module instance.

deviceSettings()

Create a Device Settings Module object.

This will start a thread for running an asynchronous module.

Returns:

Type Description
DeviceSettingsModule

Created module instance.

disconnect()

Disconnects from the data server.

Important

During the destruction the connection is closed properly. This function therefore does not need to be called in normal usage.

disconnectDevice(dev)

Disconnect a device from the data server.

This function will return immediately. The disconnection of the device may not yet be finished. Args: dev: Device serial string of device to disconnect.

echoDevice(dev)

Deprecated, see the 'sync' command.

Sends an echo command to a device and blocks until answer is received. This is useful to flush all buffers between API and device to enforce that further code is only executed after the device executed a previous command. Args: dev: Device string e.g. 'dev100'.

flush()

Deprecated, see the 'sync' command.

The flush command is identical to the sync command.

get(paths, *, flat=False, flags=0, settingsonly=True, subscribedonly=False, basechannelonly=False, excludevectors=False)

Return a dict with all nodes from the specified sub-tree. Note: Flags are ignored for a path that specifies one or more leaf nodes. Specifying flags, either as positional or keyword argument is mandatory if an empty set would be returned given the default flags (settingsonly). High-speed streaming nodes (e.g. /devN/demods/0/sample) are are never returned.

Parameters:

Name Type Description Default
paths str

Path string of the node. Multiple paths can be specified as a comma-separated list. Wild cards are supported to select multiple matching nodes.

 required
flat bool

Specify which type of data structure to return. Return data either as a flat dict (True) or as a nested dict tree (False, default).

 False
flags Union[ziListEnum, int]

Flags specifying how the selected nodes are listed (see zhinst.core.ziListEnum). Flags can also specified by the keyword arguments below.

 0
settingsonly bool

Returns only nodes which are marked as setting (default: True).

 True
subscribedonly bool

Returns only subscribed nodes (default: False).

 False
basechannelonly bool

Return only one instance of a node in case of multiple channels (default: False).

 False
excludevectors bool

Exclude vector nodes (default: False).

 False

Returns:

Type Description
LabOneResultNested

A dict with all nodes from the specified sub-tree.

getAsEvent(path)

Trigger an event on the specified node.

The node data is returned by a subsequent poll command.

Parameters:

Name Type Description Default
path str

Path string of the node. Note: Wildcards and paths referring to streaming nodes are not permitted.

 required

getAuxInSample(path)

Returns a single auxin sample.

The auxin data is averaged in contrast to the auxin data embedded in the demodulator sample.

Parameters:

Name Type Description Default
path str

Path string of the node

 required

getByte(path)

Get a byte array (string) value from the specified node.

Parameters:

Name Type Description Default
path str

Path string of the node.

 required

Returns:

Type Description
str

Byte array (string) value.

getComplex(path)

Get a complex double value from the specified node.

Parameters:

Name Type Description Default
path str

Path string of the node.

 required

Returns:

Type Description
complex

Complex double value.

getConnectionAPILevel()

Returns ziAPI level used for the active connection.

DEPRECATED, use api_level.

Returns:

Type Description
Literal[0, 1, 4, 5, 6]

ziAPI level used for the active connection.

getDIO(path)

Returns a single DIO sample.

Parameters:

Name Type Description Default
path str

Path string of the node

 required

Returns:

Type Description
Dict[str, ndarray]

Single DIO sample.

getDebugLogpath()

Path where logfiles are stored.

Note, it will return an empty string if the path has not been set or logging has not been enabled via setDebugLevel().

Returns:

Type Description
str

Path to directory where logfiles are stored.

getDouble(path)

Get a double value from the specified node.

Parameters:

Name Type Description Default
path str

Path string of the node.

 required

Returns:

Type Description
float

Floating point double value.

getInt(path)

Get a integer value from the specified node.

Parameters:

Name Type Description Default
path str

Path string of the node.

 required

Returns:

Type Description
int

Integer value.

getList(path, flags=8)

DEPRECATED: superseded by get(...).

Return a list with all nodes from the specified sub-tree. Args: path: Path string of the node. Use wild card to select all. flags: Specify which type of nodes to include in the result. Allowed: ZI_LIST_NODES_SETTINGSONLY = 0x08 (default) ZI_LIST_NODES_ALL = 0x00 (all nodes)

getSample(path)

Returns a single demodulator sample (including DIO and AuxIn).

For more efficient data recording use subscribe and poll methods!

Parameters:

Name Type Description Default
path str

Path string of the node

 required

Returns:

Type Description
Dict[str, ndarray]

Single demodulator sample (including DIO and AuxIn).

getString(path)

Get a string value from the specified node.

Parameters:

Name Type Description Default
path str

Path string of the node.

 required

Returns:

Type Description
str

String value.

getStringUnicode(path)

Get a unicode encoded string value from the specified node.

Deprecated, please use getString instead. Args: path: Path string of the node.

Returns:

Type Description
str

Unicode encoded string value.

help(path)

Prints a well-formatted description of a node.

HF2 devices do not support this functionality.

Parameters:

Name Type Description Default
path str

Path for which the nodes should be listed. The path may contain wildcards so that the returned nodes do not necessarily have to have the same parents.

 required

impedanceModule()

Create a ImpedanceModule object.

This will start a thread for running an asynchronous module.

Returns:

Type Description
ImpedanceModule

Created module instance.

listNodes(path, *, flags=None, recursive=False, absolute=False, leavesonly=False, settingsonly=False, streamingonly=False, subscribedonly=False, basechannelonly=False, getonly=False, excludevectors=False, excludestreaming=False)

This function returns a list of node names found at the specified path.

Parameters:

Name Type Description Default
path str

Path for which the nodes should be listed. The path may contain wildcards so that the returned nodes do not necessarily have to have the same parents.

 required
flags Optional[Union[ziListEnum, int]]

Flags specifying how the selected nodes are listed (see zhinst.core.ziListEnum). Flags can also specified by the keyword arguments below.

 None
recursive bool

Returns the nodes recursively (default: False)

 False
absolute bool

Returns absolute paths (default: True)

 False
leavesonly bool

Returns only nodes that are leaves, which means they are at the outermost level of the tree (default: False).

 False
settingsonly bool

Returns only nodes which are marked as setting (default: False).

 False
streamingonly bool

Returns only streaming nodes (default: False).

 False
subscribedonly bool

Returns only subscribed nodes (default: False).

 False
basechannelonly bool

Return only one instance of a node in case of multiple channels (default: False).

 False
getonly bool

Return only nodes that can be used in a get request

 False
excludestreaming bool

Exclude streaming nodes (default: False).

 False
excludevectors bool

Exclude vector nodes (default: False).

 False

Returns:

Type Description
List[str]

List of node names.

listNodesJSON(path, *, flags=None, recursive=False, absolute=False, leavesonly=False, settingsonly=False, streamingonly=False, subscribedonly=False, basechannelonly=False, getonly=False, excludevectors=False, excludestreaming=False)

Returns a list of nodes with description found at the specified path.

HF2 devices do not support this functionality.

Parameters:

Name Type Description Default
path str

Path for which the nodes should be listed. The path may contain wildcards so that the returned nodes do not necessarily have to have the same parents.

 required
flags Optional[Union[ziListEnum, int]]

Flags specifying how the selected nodes are listed (see zhinst.core.ziListEnum). Flags can also specified by the keyword arguments below. They are the same as for listNodes(), except that recursive, absolute, and leavesonly are enforced.

 None
settingsonly bool

Returns only nodes which are marked as setting (default: False).

 False
streamingonly bool

Returns only streaming nodes (default: False).

 False
subscribedonly bool

Returns only subscribed nodes (default: False).

 False
basechannelonly bool

Return only one instance of a node in case of multiple channels (default: False).

 False
getonly bool

Return only nodes that can be used in a get request

 False
excludestreaming bool

Exclude streaming nodes (default: False).

 False
excludevectors bool

Exclude vector nodes (default: False).

 False

Returns:

Type Description
List[str]

JSON dictionary nodepath:information

logOff()

Disables logging of commands sent to a server.

logOn(flags, filename, style=2)

Enables logging of commands sent to a server.

Parameters:

Name Type Description Default
flags int

Flags (LOG_NONE: 0x00000000 LOG_SET_DOUBLE: 0x00000001 LOG_SET_INT: 0x00000002 LOG_SET_BYTE: 0x00000004 LOG_SET_STRING: 0x00000008 LOG_SYNC_SET_DOUBLE: 0x00000010 LOG_SYNC_SET_INT: 0x00000020 LOG_SYNC_SET_BYTE: 0x00000040 LOG_SYNC_SET_STRING: 0x00000080 LOG_GET_DOUBLE: 0x00000100 LOG_GET_INT: 0x00000200 LOG_GET_BYTE: 0x00000400 LOG_GET_STRING: 0x00000800 LOG_GET_DEMOD: 0x00001000 LOG_GET_DIO: 0x00002000 LOG_GET_AUXIN: 0x00004000 LOG_GET_COMPLEX: 0x00008000 LOG_LISTNODES: 0x00010000 LOG_SUBSCRIBE: 0x00020000 LOG_UNSUBSCRIBE: 0x00040000 LOG_GET_AS_EVENT: 0x00080000 LOG_UPDATE: 0x00100000 LOG_POLL_EVENT: 0x00200000 LOG_POLL: 0x00400000 LOG_ALL : 0xffffffff)

 required
filename str

Log file name.

 required
style Literal[0, 1, 2]

Log style (LOG_STYLE_TELNET: 0, LOG_STYLE_MATLAB: 1, LOG_STYLE_PYTHON: 2 (default)).

 2

multiDeviceSyncModule()

Create a MultiDeviceSyncModule object.

This will start a thread for running an asynchronous module.

Returns:

Type Description
MultiDeviceSyncModule

Created module instance.

pidAdvisor()

Create a PID Advisor Module object.

This will start a thread for running an asynchronous module.

Returns:

Type Description
PidAdvisorModule

Created module instance.

poll(recording_time_s, timeout_ms, flags=0, flat=False)

Poll all Events available before and within an given time period.

Continuously check for value changes (by calling pollEvent) in all subscribed nodes for the specified duration and return the data. If no value change occurs in subscribed nodes before duration + timeout, poll returns no data. This function call is blocking (it is synchronous). However, since all value changes are returned since either subscribing to the node or the last poll (assuming no buffer overflow has occurred on the Data Server), this function may be used in a quasi-asynchronous manner to return data spanning a much longer time than the specified duration. The timeout parameter is only relevant when communicating in a slow network. In this case it may be set to a value larger than the expected round-trip time in the network.

Parameters:

Name Type Description Default
recording_time_s float

Recording time in [s]. The function will block during that time.

 required
timeout_ms int

Poll timeout in [ms]. Recommended value is 500ms.

 required
flags int

Poll flags. DEFAULT = 0x0000: Default. FILL = 0x0001: Fill holes. THROW = 0x0004: Throw EOFError exception if sample loss is detected (only possible in combination with DETECT). DETECT = 0x0008: Detect data loss holes.

 0
flat bool

Specify which type of data structure to return. Return data either as a flat dict (True) or as a nested dict tree (False). Default = False.

 False

Returns:

Type Description
Dict[str, LabOneResultAny]

A dict with the polled events. (Empty if no event occurred within the given timeout)

pollEvent(timeout_ms)

Poll a single Event.

An event are one or multiple changes that occurred in one single subscribed node. This is a low-level function to obtain a single event from the data server connection. To get all data waiting in the buffers, this command should be executed continuously until an empty dict is returned.

The poll() function is better suited in many cases, as it returns the data accumulated over some time period. Args: timeout_ms: Poll timeout in [ms]. Recommended value is 500ms.

Returns:

Type Description
Dict[str, LabOneResultAny]

A dict with the polled event. (Empty if no event occurred within the given timeout)

precompensationAdvisor()

Create a PrecompensationAdvisorModule object.

This will start a thread for running an asynchronous module.

Returns:

Type Description
PrecompensationAdvisorModule

Created module instance.

programRT(dev, filename)

Program RT. Only relevant for a HF2 device.

Parameters:

Name Type Description Default
dev str

Device identifier e.g. 'dev99'.

 required
filename str

File name of the RT program.

 required

quantumAnalyzerModule()

Create a QuantumAnalyzerModule object.

This will start a thread for running an asynchronous module.

Returns:

Type Description
QuantumAnalyzerModule

Created module instance.

record()

revision()

Get the revision number of the Python interface of Zurich Instruments.

Returns:

Type Description
int

Revision number.

scopeModule()

Create a ScopeModule object.

This will start a thread for running an asynchronous module.

Returns:

Type Description
ScopeModule

Created module instance.

set(items_or_path, value=None)

Overloaded function.

  1. set(self, items: _MultipleNodeItems)

    Set multiple nodes. items is a list of path/value pairs.

    A transaction is used to optimize the data transfer.

  2. set(self, path: str, value: Any)

    Set a single node value. path is the node path and value the value to set.

Parameters:

Name Type Description Default
items_or_path Union[Union[List[Tuple[str, Any]], Tuple[Tuple[str, Any]]], str]

A list of path/value pairs or the node path string.

 required
value Optional[Any]

The value to set in case of a single node set (items is the node path).

 None

setByte(path, value)

Set the value as byte array (string) for a specified node.

The command blocks until the data server has acknowledgement the set request.

Parameters:

Name Type Description Default
path str

Path string of the node.

 required
value Any

Value of the node.

 required

setComplex(path, value)

Set the value as complex double for a specified node.

The command blocks until the data server has acknowledgement the set request.

Parameters:

Name Type Description Default
path str

Path string of the node.

 required
value complex

Value of the node.

 required

setDebugLevel(severity)

Enables debug log and sets the debug level.

Resets the debug levels for individual sinks.

Parameters:

Name Type Description Default
severity Literal[0, 1, 2, 3, 4, 5, 6]

Debug level (trace:0, debug:1, info:2, status:3, warning:4, error:5, fatal:6).

 required

setDebugLevelConsole(severity)

Enables debug log and sets the debug level for the console output. Args: severity: Debug level (trace:0, debug:1, info:2, status:3, warning:4, error:5, fatal:6).

setDebugLevelFile(severity)

Enables debug log and sets the debug level for the file output. Args: severity: Debug level (trace:0, debug:1, info:2, status:3, warning:4, error:5, fatal:6).

setDebugLogpath(path)

Sets the path where logfiles are stored.

Note, it will restart logging if it was already enabled via setDebugLevel().

Parameters:

Name Type Description Default
path str

Path to directory where logfiles are stored.

 required

setDeprecated(items)

DEPRECATED: superseded by set(...).

Set multiple nodes.

Parameters:

Name Type Description Default
items Union[List[Tuple[str, Any]], Tuple[Tuple[str, Any]]]

A list of path/value pairs.

 required

setDouble(path, value)

Set the value as double for a specified node.

The command blocks until the data server has acknowledgement the set request.

Parameters:

Name Type Description Default
path str

Path string of the node.

 required
value float

Value of the node.

 required

setInt(path, value)

Set the value as integer for a specified node.

The command blocks until the data server has acknowledgement the set request.

Parameters:

Name Type Description Default
path str

Path string of the node.

 required
value int

Value of the node.

 required

setString(path, value)

Set the value as string for a specified node.

The command blocks until the data server has acknowledgement the set request.

Parameters:

Name Type Description Default
path str

Path string of the node.

 required
value str

Value of the node.

 required

setVector(path, value)

Set the value for a specified vector node.

The command is different from the other set commands and is Optimized for vector transfer. It blocks until the device itself has acknowledged the complete vector data set.

Parameters:

Name Type Description Default
path str

Path string of the node.

 required
value Union[ndarray, List[Union[int, float, complex]], Tuple[Union[int, float, complex], ...], str]

Vector ((u)int8, (u)int16, (u)int32, (u)int64, float, double) or string to write.

 required

subscribe(path)

Subscribe to one or several nodes.

Fetch data with the poll command. In order to avoid fetching old data that is still in the buffer, execute a sync command before subscribing to data streams.

Parameters:

Name Type Description Default
path Union[str, List[str]]

Path string of the node. Use wild card to select all. Alternatively also a list of path strings can be specified.

 required

sweep()

Create a Sweeper Module object.

This will start a thread for running an asynchronous module.

Returns:

Type Description
SweeperModule

Created module instance.

sync()

Synchronize all data paths. Ensures that get and poll commands return data which was recorded after the setting changes in front of the sync command. This sync command replaces the functionality of all syncSet, flush, and echoDevice commands.

Warning

This blocks until all devices connected to the data server report a ready state! This can take up to a minute.

syncSetDouble(path, value)

Synchronously set the value as double for a specified node.

Synchronously means that the command is blocking until the device has acknowledged the set request.

Warning

This command takes significantly longer than a non sync command and should be used with care.

Parameters:

Name Type Description Default
path str

Path string of the node.

 required
value float

Value of the node.

 required

Returns:

Type Description
float

Acknowledged value by the device.

syncSetInt(path, value)

Synchronously set the value as integer for a specified node.

Synchronously means that the command is blocking until the device has acknowledged the set request.

Warning

This command takes significantly longer than a non sync command and should be used with care.

Parameters:

Name Type Description Default
path str

Path string of the node.

 required
value int

Value of the node.

 required

Returns:

Type Description
int

Acknowledged value by the device.

syncSetString(path, value)

Synchronously set the value as string for a specified node.

Synchronously means that the command is blocking until the device has acknowledged the set request.

Warning

This command takes significantly longer than a non sync command and should be used with care.

Parameters:

Name Type Description Default
path str

Path string of the node.

 required
value str

Value of the node.

 required

Returns:

Type Description
str

Acknowledged value by the device.

unsubscribe(path)

Unsubscribe data streams.

Use this command after recording to avoid buffer overflows that may increase the latency of other command.

Parameters:

Name Type Description Default
path Union[str, List[str]]

Path string of the node. Use wild card to select all. Alternatively also a list of path strings can be specified.

 required

update()

Check if additional devices are attached.

Only revelant for connections to an HF2 Data Server. This function is not needed for servers running under windows as devices will be detected automatically.

version()

Get version string of the Python interface of Zurich Instruments.

writeDebugLog(severity, message)

Outputs message to the debug log (if enabled).

Parameters:

Name Type Description Default
severity Literal[0, 1, 2, 3, 4, 5, 6]

Debug level (trace:0, debug:1, info:2, status:3, warning:4, error:5, fatal:6). message: Message to output to the log.

 required

zoomFFT()

Create a zoomFFT Module object.

This will start a thread for running an asynchronous module.

Returns:

Type Description
ZoomFFTModule

Created module instance.

build_docstring_configure(old_docstring, new_first_line)

Builds a good docstring for a configure-func.

Assumes Google-style docstring, e.g. sections are named Args, Returns, ...

Parameters:

Name Type Description Default
old_docstring str

docstring of wrapped get_settings function

 required
new_first_line str

defines how the first line of the created docstring will look like

 required

compile_seqc(code, devtype, options, index, samplerate=None, sequencer=None, wavepath=None, waveforms=None, filename=None)

Compile the sequencer code.

This function is a purely static function that does not require an active connection to a Data Server.

.. versionadded:: 22.08

Parameters:

Name Type Description Default
code str

SeqC input

 required
devtype str

target device type, e.g., HDAWG8, SHFQC

 required
options Union[str, List[str]]

list of device options, or string of options separated by newlines as returned by node /dev.../features/options.

 required
index int

index of the AWG core

 required
samplerate Optional[float]

target sample rate of the sequencer Mandatory and only respected for HDAWG. Should match the value set on the device: /dev.../system/clocks/sampleclock/freq.

 None
sequencer Optional[str]

one of 'qa', 'sg', or 'auto'. Mandatory for SHFQC.

 None
wavepath Optional[str]

path to directory with waveforms. Defaults to path used by LabOne UI or AWG Module.

 None
waveforms Optional[str]

list of CSV waveform files separated by ';'. Defaults to an empty list. Set to None to include all CSV files in wavepath.

 None
filename Optional[str]

name of embedded ELF filename.

 None

Returns:

Type Description
Tuple[bytes, Dict[str, Any]]

Tuple (elf, extra) of binary ELF data for sequencer and extra dictionary with compiler output.
Note

The same function is available in the zhinst-seqc-compiler package. zhinst.core.compile_seqc will forward the call to zhinst.seqc_compiler.compile_seqc if a compatible version of this package is installed. A version is compatible if major and minor package versions match, and the revision of zhinst-seqc-compiler is greater or equal to the revision of zhinst-core. A warning will be issued if the versions do not match.

configure_maker(get_setting_func, build_docstring_from_old_one)

Creates a wrapper which applies the settings provided by a given function.

Parameters:

Name Type Description Default
get_setting_func Callable[..., List[Tuple[str, Any]]]

Function which provides a list of settings for a device.

 required
build_docstring_from_old_one Callable[[str], str]

Function for dynamically creating a helpful docstring out of the one from the get_settings_func

 required

Returns:

Type Description
Callable[[ziDAQServer, Any], None]

Function which applies all the settings that the get_settings_func provides

enable_result_logger(daq, device_id, channel_index, *, mode, acknowledge_timeout=1.0)

Resets and enables a specified result logger.

Blocks until the host has received the enable acknowledgment from the device.

Parameters:

Name Type Description Default
daq ziDAQServer

Instance of a Zurich Instruments API session connected to a Data Server. The device with identifier device_id is assumed to already be connected to this instance.

 required
device_id str

SHFQA device identifier, e.g. dev12004 or 'shf-dev12004'.

 required
channel_index int

Index specifying which result logger to enable - there is one result logger per channel.

 required
mode str

Select between "spectroscopy" and "readout" mode.

 required
acknowledge_timeout float

Maximum time to wait for diverse acknowledgments in the implementation.

.. versionadded:: 0.1.1

 1.0

enable_scope(daq, device_id, *, single, acknowledge_timeout=1.0)

Resets and enables the scope.

Blocks until the host has received the enable acknowledgment from the device.

Parameters:

Name Type Description Default
daq ziDAQServer

Instance of a Zurich Instruments API session connected to a Data Server. The device with identifier device_id is assumed to already be connected to this instance.

 required
device_id str

SHFQA device identifier, e.g. dev12004 or 'shf-dev12004'.

 required
single int

0 = continuous mode, 1 = single-shot.

 required
acknowledge_timeout float

Maximum time to wait for diverse acknowledgments in the implementation.

.. versionadded:: 0.1.1

 1.0

enable_sequencer(daq, device_id, channel_index, *, single)

Starts the sequencer of a specific channel.

Parameters:

Name Type Description Default
daq ziDAQServer

Instance of a Zurich Instruments API session connected to a Data Server. The device with identifier device_id is assumed to already be connected to this instance.

 required
device_id str

SHFQA device identifier, e.g. dev12004 or 'shf-dev12004'.

 required
channel_index int

Index specifying which sequencer to enable - there is one sequencer per channel.

 required
single int

1 - Disable sequencer after finishing execution. 0 - Restart sequencer after finishing execution.

 required

get_channel_settings(device_id, channel_index, *, input_range, output_range, center_frequency, mode)

Provides a list of settings for the RF input and output of a specified channel.

This function only gathers all node settings and does not apply the values on the device. It is intended to be used by higher-level APIs for simpler integrations. Instead of using this function directly, consider calling 'configure_channel', which will also apply the settings on the device.

Parameters:

Name Type Description Default
device_id str

SHFQA device identifier, e.g. dev12004 or 'shf-dev12004'.

 required
channel_index int

Index specifying which channel to configure.

 required
input_range int

Maximal range of the signal input power in dbM.

 required
output_range int

Maximal range of the signal output power in dbM.

 required
center_frequency float

Center Frequency of the analysis band.

 required
mode str

Select between "spectroscopy" and "readout" mode.

 required

get_configure_weighted_integration_settings(device_id, channel_index, *, weights, integration_delay=0.0, integration_length=None, clear_existing=True)

Provides a list of settings for a weighted integration.

Parameters:

Name Type Description Default
device_id str

SHFQA device identifier, e.g. dev12004 or 'shf-dev12004'.

 required
channel_index int

Index specifying which group of integration units the integration weights should be uploaded to - each channel is associated with a number of integration units that depend on available device options. Please refer to the SHFQA manual for more details.

 required
weights dict

Dictionary containing the complex weight vectors, where keys correspond to the indices of the integration units to be configured.

 required
integration_delay float

Delay in seconds before starting readout.

 0.0
integration_length Optional[int]

Number of samples over which the weighted integration runs. If set to None, the integration length is determined by the length of the first weights vector.

 None
clear_existing bool

Specify whether to set all the integration weights to zero before proceeding with the present upload.

 True

get_result_logger_data(daq, device_id, channel_index, *, mode, timeout=1.0)

Return the measured data of a specified result logger.

Blocks until the specified result logger is finished.

Parameters:

Name Type Description Default
daq ziDAQServer

Instance of a Zurich Instruments API session connected to a Data Server. The device with identifier device_id is assumed to already be connected to this instance.

 required
device_id str

SHFQA device identifier, e.g. dev12004 or 'shf-dev12004'.

 required
channel_index int

Index specifying which result logger to query results from - there is one result logger per channel.

 required
mode str

Select between "spectroscopy" and "readout" mode.

 required
timeout float

Maximum time to wait for data in seconds.

 1.0

Returns:

Type Description
array

Array containing the result logger data.

get_result_logger_for_readout_settings(device_id, channel_index, *, result_source, result_length, num_averages=1, averaging_mode=0)

Provides a list of settings for a specified result logger for readout mode.

This function only gathers all node settings and does not apply the values on the device. It is intended to be used by higher-level APIs for simpler integrations. Instead of using this function directly, consider calling 'configure_result_logger_for_readout', which will also apply the settings on the device.

Parameters:

Name Type Description Default
device_id str

SHFQA device identifier, e.g. dev12004 or 'shf-dev12004'.

 required
channel_index int

Index specifying which result logger to configure - there is one result logger per channel.

 required
result_source str

String-based tag to select the result source in readout mode, e.g. "result_of_integration" or "result_of_discrimination".

 required
result_length int

Number of results to be returned by the result logger.

 required
num_averages int

Number of averages, will be rounded to 2^n.

 1
averaging_mode int

Select the averaging order of the result, with 0 = cyclic and 1 = sequential.

 0

get_result_logger_for_spectroscopy_settings(device_id, channel_index, *, result_length, num_averages=1, averaging_mode=0)

Provides a list of settings for a specified result logger for spectroscopy mode.

This function only gathers all node settings and does not apply the values on the device. It is intended to be used by higher-level APIs for simpler integrations. Instead of using this function directly, consider calling 'configure_result_logger_for_spectroscopy', which will also apply the settings on the device.

Parameters:

Name Type Description Default
device_id str

SHFQA device identifier, e.g. dev12004 or 'shf-dev12004'.

 required
channel_index int

Index specifying which result logger to configure - there is one result logger per channel.

 required
result_length int

Number of results to be returned by the result logger

 required
num_averages int

Number of averages, will be rounded to 2^n.

 1
averaging_mode int

Select the averaging order of the result, with 0 = cyclic and 1 = sequential.

 0

get_scope_data(daq, device_id, *, timeout=5.0)

Queries the scope for data once it is finished.

Parameters:

Name Type Description Default
daq ziDAQServer

Instance of a Zurich Instruments API session connected to a Data Server. The device with identifier device_id is assumed to already be connected to this instance.

 required
device_id str

SHFQA device identifier, e.g. dev12004 or 'shf-dev12004'.

 required
timeout float

Maximum time to wait for the scope data in seconds.

 5.0

Returns:

Type Description
tuple

Three-element tuple with: * recorded_data (array): Contains an array per scope channel with the recorded data. * recorded_data_range (array): Full scale range of each scope channel. * scope_time (array): Relative acquisition time for each point in recorded_data in seconds starting from 0.

get_scope_settings(device_id, *, input_select, num_samples, trigger_input, num_segments=1, num_averages=1, trigger_delay=0.0)

Provides a list of settings for the scope for a measurement.

This function only gathers all node settings and does not apply the values on the device. It is intended to be used by higher-level APIs for simpler integrations. Instead of using this function directly, consider calling 'configure_scope', which will also apply the settings on the device.

Parameters:

Name Type Description Default
device_id str

SHFQA device identifier, e.g. dev12004 or 'shf-dev12004'.

 required
input_select dict

Keys (int) map a specific scope channel with a signal source (str), e.g. "channel0_signal_input". For a list of available values use daq.help(f"/{device_id}/scopes/0/channels/0/inputselect").

 required
num_samples int

Number of samples in the scope shot.

 required
trigger_input str

Specifies the trigger source of the scope acquisition - if set to None, the self-triggering mode of the scope becomes active, which is useful e.g. for the GUI. For a list of available trigger values use daq.help(f"/{device_id}/scopes/0/trigger/channel").

 required
num_segments int

Number of distinct scope shots to be returned after ending the acquisition.

 1
num_averages int

Specifies how many times each segment should be averaged on hardware; to finish a scope acquisition, the number of issued triggers must be equal to num_segments * num_averages.

 1
trigger_delay float

Delay in samples specifying the time between the start of data acquisition and reception of a trigger.

 0.0

get_sequencer_triggering_settings(device_id, channel_index, *, aux_trigger, play_pulse_delay=0.0)

Provides a list of settings for the triggering of a specified sequencer.

This function only gathers all node settings and does not apply the values on the device. It is intended to be used by higher-level APIs for simpler integrations. Instead of using this function directly, consider calling 'configure_sequencer_triggering', which will also apply the settings on the device.

Parameters:

Name Type Description Default
device_id str

SHFQA device identifier, e.g. dev12004 or 'shf-dev12004'.

 required
channel_index int

Index specifying on which sequencer to configure the triggering - there is one sequencer per channel.

 required
aux_trigger str

Alias for the trigger used in the sequencer. For a list of available values use. daq.help(f"/{device_id}/qachannels/0/generator/auxtriggers/0/channel")

 required
play_pulse_delay float

Delay in seconds before the start of waveform playback.

 0.0

load_sequencer_program(daq, device_id, channel_index, sequencer_program, **_)

Compiles and loads a program to a specified sequencer.

This function is composed of 4 steps
  1. Reset the generator to ensure a clean state.
  2. Compile the sequencer program with the offline compiler.
  3. Upload the compiled binary elf file.
  4. Validate that the upload was successful and the generator is ready again.

Parameters:

Name Type Description Default
daq ziDAQServer

Instance of a Zurich Instruments API session connected to a Data Server. The device with identifier device_id is assumed to already be connected to this instance.

 required
device_id str

SHFQA device identifier, e.g. dev12004 or 'shf-dev12004'.

 required
channel_index int

Index specifying to which sequencer the program below is uploaded - there is one sequencer per channel.

 required
sequencer_program str

Sequencer program to be uploaded.

 required

Raises:

Type Description
RuntimeError

If the Upload was not successfully or the device could not process the sequencer program.

max_qubits_per_channel(daq, device_id)

Returns the maximum number of supported qubits per channel.

Parameters:

Name Type Description Default
daq ziDAQServer

Instance of a Zurich Instruments API session connected to a Data Server. The device with identifier device_id is assumed to already be connected to this instance.

 required
device_id str

SHFQA device identifier, e.g. dev12004 or 'shf-dev12004'.

 required

start_continuous_sw_trigger(daq, device_id, *, num_triggers, wait_time)

Issues a specified number of software triggers.

Issues a specified number of software triggers with a certain wait time in between. The function guarantees reception and proper processing of all triggers by the device, but the time between triggers is non-deterministic by nature of software triggering.

Warning

Only use this function for prototyping and/or cases without strong timing requirements.

Parameters:

Name Type Description Default
daq ziDAQServer

Instance of a Zurich Instruments API session connected to a Data Server. The device with identifier device_id is assumed to already be connected to this instance.

 required
device_id str

SHFQA device identifier, e.g. dev12004 or 'shf-dev12004'.

 required
num_triggers int

Number of triggers to be issued.

 required
wait_time float

Time between triggers in seconds.

 required

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.

write_to_waveform_memory(daq, device_id, channel_index, waveforms, *, clear_existing=True)

Writes pulses to the waveform memory of a specified generator.

Parameters:

Name Type Description Default
daq ziDAQServer

Instance of a Zurich Instruments API session connected to a Data Server. The device with identifier device_id is assumed to already be connected to this instance.

 required
device_id str

SHFQA device identifier, e.g. dev12004 or 'shf-dev12004'.

 required
channel_index int

Index specifying which generator the waveforms below are written to - there is one generator per channel.

 required
waveforms dict

Dictionary of waveforms, the key specifies the slot to which to write the value which is a complex array containing the waveform samples.

 required
clear_existing bool

Specify whether to clear the waveform memory before the present upload.

 True