AWG Module

The allows programmers to access the functionality available in the LabOne User Interface AWG tab. It allows users to compile and upload sequencer programs to the arbitrary waveform generator on UHF and HDAWG instruments from any of the LabOne APIs.

This chapter only explains the specifics for working with an AWG from an API; reference documentation of the LabOne AWG Sequencer Programming Language can be found in the UHF or HDAWG User Manual.

Figure 1. An AWG signal generated and measured using a UHFLI with the AWG Option. The waveform data was measured via a feedback cable using the UHF’s Scope. The plot was generated by the Python API example for the UHF, example_awg.py, which also generates the expected waveform and cross-correlates it with the measured waveform in order to overlay the expected signal on the measurement data.

Getting Started with the AWG Module

The following API examples demonstrating AWG Module use are available:

Matlab and Python, example_awg.{py,m}: Compiles and uploads an AWG sequencer program from a string. It demonstrates how to define waveforms using the four methods listed below in Methods to define Waveforms in Sequencer Programs. Separate versions of these examples are available for both UHF and HDAWG instruments.
Matlab and Python, example_awg_sourcefile.{py,m}: Demonstrates how to compile and upload an AWG sequencer program from a .seqc file. Separate versions of these examples are available for both UHF and HDAWG instruments.
LabVIEW, ziExample-UHFLI-Module-AWG.vi: Compiles and uploads an AWG sequencer program from a string and captures the generated waveform in the scope (UHF only).
.NET, ExampleAwgModule() (in Examples.cs): Compiles and uploads an AWG sequencer program from a string. It demonstrates how to define waveforms using the four methods listed below in Methods to define Waveforms in Sequencer Programs.
C API, ExampleAWGUpload.c: Demonstrates how to compile and upload an AWG sequencer program from a .seqc file.

Sequencer Program Compilation and Upload

Programming an AWG with a sequencer program is a 2-step process. First, the source code must be compiled to a binary ELF file and secondly the ELF file must be uploaded from the PC to the AWG on the UHF or HDAWG instrument. Both steps are performed by an instance of the AWG Module regardless of whether the module is used in the API or the LabOne User Interface’s AWG Sequencer tab.

Compilation

An AWG sequencer program can be provided to the AWG module for compilation as either a:

Source file: In this case the sequencer program file must reside in the "awg/src" sub-directory of the LabOne user directory. The filename (without full directory path) must be specified via the awgModule/compiler/sourcefile parameter and compilation is started when the in-out parameter awgModule/compiler/start is set to 1.
String: A sequencer program may also be sent directly to the AWG Module as a string (comprising of a valid sequencer program) without the need to create a file on disk. The string is sent to the module by writing it to the awgModule/compiler/sourcestring using the module setString() function. In this case, compilation is started automatically after writing the source string.

Upload

If the awgModule/compiler/upload parameter is set to 1 the ELF file is automatically uploaded to the AWG after successful compilation. Otherwise, it must be uploaded by setting the in-out parameter awgModule/elf/upload to 1. A running AWG must be disabled first in order to upload a new sequencer program and it must be enabled again after upload.

Methods to define Waveforms in Sequencer Programs

The waveforms played by an AWG sequencer program can be defined, or in the last case, modified, using the following four methods. These methods are demonstrated by the examples listed in Getting Started with the AWG Module.

By using one of the waveform generation functions such as sine(), sinc(), gauss(), etc. defined in the LabOne AWG Sequencer programming language. See the UHF or HDAWG User Manual for full reference documentation.
By defining a waveform in floating point format in a CSV file. Such waveform CSV files must be located in the "awg/waveforms" sub-directory of the LabOne user directory (see explanation of awgModule/directory in Table 5). In order to compile a sequencer program that uses CSV-defined waveforms a comma-separated list of the CSV filenames (without extension) must be specified via the awgModule/compiler/waveforms parameter.
By defining a short waveform as an array of floating point numbers within the sequencer program and playing it using the AWG Sequencer function vect(). Note, this method should only be used for short waveforms (less than 100 points); a compiler warning is issued when vect() is used with a larger number of input arguments. For longer waveforms it’s recommended to define the waveform in a CSV file as described above instead.
A waveform that has been previously defined, even as an array of zeros with, for example, zeros(10000), may be replaced at program runtime as follows:
```
Writing the new waveform vector using the setVector command to the node /DEV.../AWGS/0/WAVEFORM/WAVES/<index> where <index> corresponds to the desired waveform to replace.
```
Note that the new waveform must be the same length as the original defined in the sequence program. Note also that the /DEV…/AWGS/0/WAVEFORM/WAVES/<index> nodes have the property SILENTWRITE. This means that subscribing to such a node has no effect, i.e. changes to the node will not be returned in poll. To obtain the contents of such nodes, getAsEvent has to be called followed by poll. For short vectors get may be used. The index of the waveform to replace is defined as follows: Let N be the total number of waveforms and M>0 be the number of waveforms used in the sequencer program defined from CSV file. Then the index of the waveform to replace is defined as follows:
- index=0,…,M-1 for all waveforms defined from CSV alphabetically ordered by filename,
- index=M,…,N-1 in the order that the other (non-CSV defined) waveforms are defined in the sequencer program.
If no waveforms are defined by CSV file (M=0), then the index is defined by:
- index=0,…,N-1 in the order that the waveforms are defined in the sequencer program.
Alternatively, the index of the waveform to be replaced can be determined using the Waveform sub-tab in the AWG tab of the LabOne User Interface.

The waveform nodes use the internal raw format of the instrument and map the hardware capabilities of an AWG core. Thus, each waveform node can hold up to two analog waveforms and four markers. The length, number of waves and the presence of markers must be the same as the original. An analog waveform is represented as array of signed int16. The markers are represented as array of int16, with the marker values defined in the four LSB; the other 12 bits must be zeros (see Figure 2). If there is more than one analog waveform and/or markers, the arrays representing them must be interleaved; the order should be the first wave, then the second and finally the markers.
```
wave_int16 = int16((1 << 15 - 1) * wave_float);
markers = int16(mk1_out1 * 1 << 0 + mk2_out1 * 1 << 1 +
                mk1_out2 * 1 << 2 + mk2_out2 * 1 << 3);
```
It’s convenient to use the helper Python functions zhinst.utils.convert_awg_waveform and zhinst.utils.parse_awg_waveform to write and read these nodes.

Figure 2. Interleaving of waves and markers in AWG raw format

HDAWG Channel Grouping

This section explains how to configure the awgModule/index parameter and which AWGS node branch must be used for different channel grouping configurations. The channel grouping is defined by the value of the the node /DEV…./SYSTEM/AWG/CHANNELGROUPING as follows:

0:: Use the outputs in groups of 2; each sequencer program controls 2 outputs. Each group n=0,1,2,3 of AWGs (respectively n=0,1 on HDAWG4 instruments) is configured by the /DEV…./AWGS/n branches. Each of these 4 groups requires its own instance of the AWG Module and `awgModule/index should be set to n=0,1,2,3 for each group accordingly.
1:: Use the outputs in groups of 4; each sequencer program controls 4 outputs. Each group n=0,1 of AWGs (respectively n=0 on HDAWG4 instruments) is configured by the /DEV…./AWGS/0 and /DEV…./AWGS/2 branches. Each of these two groups requires its own instance of the AWG Module and awgModule/index should be set to n=0,1 for each group accordingly. For HDAWG4 instruments, there is only one group of 4 outputs which is configured by the /DEV…./AWGS/0 branch.
2:: HDAWG8 devices only. Use the outputs in a single group of 8; the (single) sequencer program controls 8 outputs. There is only one group (n=0) of 8 AWGs which is configured by the /DEV…./AWGS/0 branch. Only one instance of the AWG Module is required and its value of awgModule/index should be 0.

Table 1. Overview of the device nodes and the value of `awgModule/index` used indifferent channel grouping configurations on HDAWG8 instruments.
Value of CHANNELGROUPING	Number of Cores	AWG Core	Corresponding device AWG branch index	Value of `awgModule/index`
0	4	1	/DEV…./AWGS/0	0
		2	/DEV…./AWGS/1	1
		3	/DEV…./AWGS/2	2
		4	/DEV…./AWGS/3	3
1	2	1	/DEV…./AWGS/0	0
1	2	2	/DEV…./AWGS/2	1
2	1	1	/DEV…./AWGS/0	0

Table 2. Overview of the device nodes and the value of `awgModule/index` used indifferent channel grouping configurations on HDAWG4 instruments.
Value of CHANNELGROUPING	Number of Cores	AWG Core	Corresponding device AWG branch index	Value of `awgModule/index`
0	2	1	/DEV…./AWGS/0	0
0	2	2	/DEV…./AWGS/1	1
1	1	1	/DEV…./AWGS/0	0

AWG Module Parameters

The following tables provide a comprehensive list of the module’s parameters, see:

Table 3 for input/output parameters,
Table 4 for input parameters and,
Table 5 for output parameters.

Table 3. AWG Module Input/Output Parameters.
Setting/Path	Type	Unit	Description
`compiler/start`	bool	-	Set to 1 to start compiling the AWG sequencer program specified by `compiler/sourcefile`. The module sets `compiler/start` to 0 once compilation has successfully completed (or failed). If `compiler/upload` is enabled then the sequencer program will additionally be uploaded to the AWG upon after successful compilation.
`elf/upload`	bool	-	Set to 1 to start uploading the AWG sequencer program to the device. The module sets `elf/upload` to 0 once the upload has finished.

Table 4. AWG Module Input Parameters.
Setting/Path	Type	Unit	Description
`compiler/sourcefile`	string	-	The filename of an AWG sequencer program file to compile and load. The file must be located in the "awg/src" sub-directory of the LabOne user directory. This directory path is provided by the value of the read-only `directory` parameter.
`compiler/sourcestring`	string	-	A string containing an AWG sequencer program may directly loaded to this parameter using the module command `setString`. This allows compilation and upload of a sequencer program without saving it to a file first. Compilation starts automatically after `compiler/sourcestring` has been set.
`compiler/upload`	bool	-	Specify whether the sequencer program should be automatically uploaded to the AWG following successful compilation.
`compiler/waveforms`	string	-	A comma-separated list of waveform CSV files to be used by the AWG sequencer program.
`device`	string	-	The target device for AWG sequencer programs upload, e.g. 'dev2006'.
`elf/file`	string	-	The filename of the compiled binary ELF file. If not set, the name is automatically set based on the source filename. The ELF file will be saved by the AWG Module in the "awg/elf" sub-directory of the LabOne user directory. This directory path is provided by the value of the read-only `directory` parameter.
`index`	bool	-	The index of the current AWG Module to use when running with multiple AWG groups, see HDAWG Channel Grouping for further explanation.
`mds/enable`	bool	-	Enables grouping of multiple synchronized instruments for AWG playback.
`mds/group`	int	-	The MDS group (`multiDeviceSyncModule/group`) to use for synchronized AWG playback.

Table 5. AWG Module Output (read-only) Parameters.
Setting/Path	Type	Unit	Description
`compiler/status`	int	-	Compilation status: 1: Idle. 0: Compilation successful. 1: Compilation failed. 2: Compilation completed with warnings.
`compiler/statusstring`	string	-	Status message of the compiler.
`directory`	string	-	The path of the LabOne user directory (this may not be modified). The AWG Module uses the following subdirectories in the LabOne user directory: awg/src Contains AWG sequencer program source files (user created). awg/elf Contains compiled AWG binary (ELF) files (created by the module). awg/waves Contains CSV waveform files (user created).
`elf/status`	int	-	Status of the ELF file upload: 1: Idle. 0: Upload successful. 1: Upload failed. 2: Upload in progress.
`elf/checksum`	int	-	The checksum of the generated ELF file.
`progress`	double	-	Reports the progress of the upload as a value between 0 and 1.