Python Toolkit API Waveform¶
zhinst.toolkit.waveform.Waveforms()
¶
Bases: MutableMapping
Waveform dictionary.
The key specifies the slot of the waveform on the device. The value is a the waveform itself, represented by a tuple (wave1, wave2, marker).
The value tuple(wave1, wave2=None, marker=None) consists of the following parts:
- wave1 (array): Array with data of waveform 1.
- wave2 (array): Array with data of waveform 2.
- markers (array): Array with marker data.
A helper function exist called assign_waveform which provides an easy way
of assigning waveforms to slots. But one can also use the direct dictionary
access:
>>> wave = 1.0 * np.ones(1008)
>>> markers = np.zeros(1008)
>>> waveforms = Waveforms()
>>> waveforms.assign_waveform(0, wave)
>>> waveforms.assign_waveform(1, wave, -wave)
>>> waveforms.assign_waveform(2, wave, -wave, markers)
>>> waveforms.assign_waveform(3, wave, markers=markers)
>>> waveforms[4] = (wave,)
>>> waveforms[5] = (wave, -wave)
>>> waveforms[6] = (wave, -wave, markers)
>>> waveforms[7] = (wave, None, markers)
The arrays can be provided as arrays of integer, float. The first wave also
can be of type complex. In that case the second waveform must be None.
Depending on the target format the function get_raw_vector converts the
waves into the following format:
- native AWG waveform format (interleaved waves and markers as uint16) that can be uploaded to the AWG waveform nodes. In case the first wave is of type complex the imaginary part is treated as the second wave.
- complex waveform format that can be uploaded to the generator waveform nodes (does not support markers). In case two real waveforms have been specified they are combined into a single complex waveform, where the imaginary part defined by the second wave.
assign_native_awg_waveform(slot, raw_waveform, channels=1, markers_present=False)
¶
Assigns a native AWG waveform to a slot.
Native AWG waveform = a single waveform (interleaved waves and markers as uint16).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
slot |
int
|
slot number |
required |
raw_waveform |
ndarray
|
native AWG waveform. |
required |
channels |
int
|
Number of channels present in the wave. (default = 1) |
1
|
markers_present |
bool
|
Indicates if markers are interleaved in the wave. (default = False) |
False
|
assign_waveform(slot, wave1, wave2=None, markers=None)
¶
Assigns a waveform to a slot.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
slot |
int
|
slot number |
required |
wave1 |
ndarray
|
Array with data of waveform 1. |
required |
wave2 |
Optional[ndarray]
|
Array with data of waveform 2. (default = None) |
None
|
markers |
Optional[ndarray]
|
Array with marker data. (default = None) |
None
|
get_raw_vector(slot, *, complex_output=False)
¶
Get the raw vector for a slot required by the device.
Either converts a waveform into the native AWG waveform format that can be uploaded to the AWG wave node or converts the waveform into a complex waveform that can be uploaded to a generator wave node. (complex_output = True).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
slot |
int
|
slot number of the waveform |
required |
complex_output |
bool
|
Flag if the output should be a complex waveform for a generator node, instead of of the native AWG format that can only be uploaded to an AWG node. (default = False) |
False
|
Returns:
| Type | Description |
|---|---|
ndarray
|
Waveform in the native AWG format or as a complex waveform |
Raises:
| Type | Description |
|---|---|
ValueError
|
The length of the waves does not match the target length. |
get_sequence_snippet()
¶
Return a sequencer code snippet for the defined waveforms.
Based on the defined waveforms and their additional information this function generates a sequencer code snippet that can be used to define the given waveforms. The following information will be used:
- Waveform length
- Waveform index
- presence of markers and for which channel
- Defined names of the waveforms (if set)
- Defined output configuration (if set)
Example
waveform = Waveform() waveform.assign_waveform( 0, wave1=Wave( np.ones(1008), name="w1", output=OutputType.OUT1 | OutputType.OUT2 ), wave2=Wave( -np.ones(1008), name="w2", output=OutputType.OUT2), markers=15 * np.ones(1008), ) waveform.get_sequence_snippet() wave w1 = placeholder(1008, true, true); wave w2 = placeholder(1008, true, true); assignWaveIndex(1, 2, w1, 2, w2, 0);
Returns:
| Type | Description |
|---|---|
str
|
Sequencer Code snippet. |
validate(meta_info, *, allow_missing=True)
¶
Validates the waveforms against the ones defined in a sequencer program.
The information about the sequencer code can either be passed in form
of a compiled elf file or a the waveform descriptor provided by the
device once a valid sequencer code was uploaded to the device.
The waveform descriptor can be read from the device through the node
<path to awg core>.waveform.descriptors
(e.g hdawg.awgs[0].waveform.descriptors()).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
meta_info |
Union[bytes, str]
|
Compiled sequencer code or the waveform descriptor. |
required |
allow_missing |
Flag if this function allows placeholder waveforms to be defined in the sequencer code that are not used in this object. This is disabled by default since uploading/replacing only a fraction of the defined waveforms is a valid use case. |
True
|
Raises:
| Type | Description |
|---|---|
TypeError
|
If the meta_info are not a compiled elf file, string or dictionary. |
ValidationError
|
If the Validation fails. |
zhinst.toolkit.waveform.Wave
¶
Bases: ndarray
Numpy array subclass containing additional waveform metadata.
This class takes a standard ndarray that already exists, casts as Wave type, and adds the following extra attributes/metadata: * name * output
The additional metadata is only used for the sequencer code generation.
(Based on https://numpy.org/doc/stable/user/basics.subclassing.html)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
input_array |
existing ndarray |
required | |
name |
optional name of the waveform in the sequencer code snippet. |
required | |
output |
optional output configuration for the waveform in the sequencer code snippet. |
required |