Python Toolkit API HDAWG

zhinst.toolkit.driver.devices.hdawg.HDAWG(serial, device_type, session)

Bases: BaseInstrument

High-level driver for the Zurich Instruments HDAWG.

awgs: t.Sequence[AWG] cached property

A Sequence of AWG Cores.

Returns:

Type	Description
Sequence[AWG]	A list of AWG objects.

enable_qccs_mode(gen=1)

Configure the instrument to work with PQSC.

This method sets the reference clock source to connect the instrument to the PQSC.

Parameters:

Name	Type	Description	Default
gen	int	The QCCS generation that is being configured. Use 1 for a gen1 system, when only HDAWG and UHFQA are used. In this case, the sample rate is set to 2.4 GSa/s and the DIO interface is configured for connection with the UHFQA. Use 2 for a gen2 system, when only HDAWG and SHFs are used. In this case, the sample rate is set to 2.0 GSa/s. (default: 1)	1

Raises:

Type	Description
ToolkitError	If the gen argument is not correct.

Info

Use factory_reset to reset the changes if necessary

zhinst.toolkit.driver.nodes.awg.AWG(root, tree, serial, index, device_type, device_options)

Bases: Node

AWG node.

This class implements the basic functionality for the device specific arbitrary waveform generator. Besides the upload/compilation of sequences it offers the upload of waveforms and command tables.

Parameters:

Name	Type	Description	Default
root	NodeTree	Root of the nodetree	required
tree	tuple	Tree (node path as tuple) of the current node	required
session		Underlying session.	required
serial	str	Serial of the device.	required
index	int	Index of the corresponding awg channel	required
device_type	str	Device type	required

commandtable: t.Optional[CommandTableNode] cached property

Command table module.

Returns:

Type	Description
Optional[CommandTableNode]	Command table module.

compile_sequencer_program(sequencer_program, **kwargs)

Compiles a sequencer program for the specific device.

Parameters:

Name	Type	Description	Default
sequencer_program	Union[str, Sequence]	The sequencer program to compile.	required

Other Parameters:

Name	Type	Description
samplerate	int	Target sample rate of the sequencer. Only allowed/ necessary for HDAWG devices. Must correspond to the samplerate used by the device (device.system.clocks.sampleclock.freq()). If not specified the function will get the value itself from the device. It is recommended passing the samplerate if more than one sequencer code is uploaded in a row to speed up the execution time.
wavepath	str	path to directory with waveforms. Defaults to path used by LabOne UI or AWG Module.
waveforms	str	waveform CSV files separated by ';'
output	str	name of embedded ELF filename.

Returns:

Name	Type	Description
elf	bytes	Binary ELF data for sequencer.
extra	dict[str, Any]	Extra dictionary with compiler output.

Example

elf, compile_info = device.awgs[0].compile_sequencer_program(seqc) device.awgs[0].elf.data(elf) device.awgs[0].ready.wait_for_state_change(1) device.awgs[0].enable(True)

Raises:

Type	Description
RuntimeError	sequencer_program is empty.
RuntimeError	If the compilation failed.

enable_sequencer(*, single)

Starts the sequencer of a specific channel.

Warning

This function is synchronous and blocks until the sequencer is enabled. When working with multiple instruments this function is the wrong approach and the sequencer should be enabled asynchronously. (For more information please take a look at the awg example in the toolkit documentation.)

Parameters:

Name	Type	Description	Default
single	bool	Flag if the sequencer should be disabled after finishing	required

Raises:

Type	Description
RuntimeError	If the sequencer could not be enabled.

load_sequencer_program(sequencer_program, **kwargs)

Compiles the given sequencer program on the AWG Core.

Warning

After uploading the sequencer program one needs to wait before for the awg core to become ready before it can be enabled. The awg core indicates the ready state through its ready node. (device.awgs[0].ready() == True)

Parameters:

Name	Type	Description	Default
sequencer_program	Union[str, Sequence]	Sequencer program to be uploaded.	required

Other Parameters:

Name	Type	Description
samplerate	int	Target sample rate of the sequencer. Only allowed/ necessary for HDAWG devices. Must correspond to the samplerate used by the device (device.system.clocks.sampleclock.freq()). If not specified the function will get the value itself from the device. It is recommended passing the samplerate if more than one sequencer code is uploaded in a row to speed up the execution time.
wavepath	str	path to directory with waveforms. Defaults to path used by LabOne UI or AWG Module.
waveforms	str	waveform CSV files separated by ';'
output	str	name of embedded ELF filename.

Example

compile_info = device.awgs[0].load_sequencer_program(seqc) device.awgs[0].ready.wait_for_state_change(1) device.awgs[0].enable(True)

Raises:

Type	Description
RuntimeError	sequencer_program is empty.
RuntimeError	If the upload or compilation failed.

read_from_waveform_memory(indexes=None)

Read waveforms from the waveform memory.

Parameters:

Name	Type	Description	Default
indexes	Optional[list[int]]	List of waveform indexes to read from the device. If not specified all assigned waveforms will be downloaded.	None

Returns:

Type	Description
Waveforms	Waveform object with the downloaded waveforms.

wait_done(*, timeout=10, sleep_time=0.005)

Wait until the AWG is finished.

Parameters:

Name	Type	Description	Default
timeout	float	The maximum waiting time in seconds for the generator (default: 10).	10
sleep_time	float	Time in seconds to wait between requesting generator state	0.005

Raises:

Type	Description
RuntimeError	If continuous mode is enabled
TimeoutError	If the sequencer program did not finish within the specified timeout time

write_to_waveform_memory(waveforms, indexes=None)

Writes waveforms to the waveform memory.

The waveforms must already be assigned in the sequencer program.

Parameters:

Name	Type	Description	Default
waveforms	Waveforms	Waveforms that should be uploaded.	required
indexes	Optional[list]	Specify a list of indexes that should be uploaded. If nothing is specified all available indexes in waveforms will be uploaded. (default = None)	None

zhinst.toolkit.driver.nodes.command_table_node.CommandTableNode(root, tree, device_type)

Bases: Node

CommandTable node.

This class implements the basic functionality of the command table allowing the user to load and upload their own command table.

A dedicated class called CommandTable exists that is the preferred way to create a valid command table. For more information about the CommandTable refer to the corresponding example or the documentation of that class directly.

Parameters:

Name	Type	Description	Default
root	NodeTree	Node used for the upload of the command table	required
tree	tuple[str, ...]	Tree (node path as tuple) of the current node	required
device_type	str	Device type.	required

check_status()

Check status of the command table.

Returns:

Type	Description
bool	Flag if a valid command table is loaded into the device.

Raises:

Type	Description
RuntimeError	If the command table upload into the device failed.

load_from_device()

Load command table from the device.

Returns:

Type	Description
CommandTable	command table.

load_validation_schema()

Load device command table validation schema.

Returns:

Type	Description
dict[str, Any]	JSON validation schema for the device command tables.

upload_to_device(ct, *, validate=False, check_upload=True)

Upload command table into the device.

The command table can either be specified through the dedicated CommandTable class or in a raw format, meaning a json string or json dict. In the case of a json string or dict the command table is validated by default against the schema provided by the device.

Parameters:

Name	Type	Description	Default
ct	Union[CommandTable, str, dict]	Command table.	required
validate	bool	Flag if the command table should be validated. (Only applies if the command table is passed as a raw json string or json dict)	False
check_upload	bool	Flag if the upload should be validated by calling check_status. This is not mandatory bat strongly recommended since the device does not raise an error when it rejects the command table. This Flag is ignored when called from within a transaction.	True

Raises:

Type	Description
RuntimeError	If the command table upload into the device failed.
ValidationError	Incorrect schema.