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.
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()
(inExamples.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:
|
Upload
If the |
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 theawgModule/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 whenvect()
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 bypoll
. For short vectorsget
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
andzhinst.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.
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 |
2 |
/DEV…./AWGS/2 |
1 |
||
2 |
1 |
1 |
/DEV…./AWGS/0 |
0 |
Value of CHANNELGROUPING | Number of Cores | AWG Core | Corresponding device AWG branch index | Value of awgModule/index |
---|---|---|---|---|
0 |
2 |
1 |
/DEV…./AWGS/0 |
0 |
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:
Setting/Path | Type | Unit | Description |
---|---|---|---|
|
bool |
- |
Set to 1 to start compiling the AWG sequencer program specified by |
|
bool |
- |
Set to 1 to start uploading the AWG sequencer program to the device. The module sets |
Setting/Path | Type | Unit | Description |
---|---|---|---|
|
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 |
|
string |
- |
A string containing an AWG sequencer program may directly loaded to this parameter using the module command |
|
bool |
- |
Specify whether the sequencer program should be automatically uploaded to the AWG following successful compilation. |
|
string |
- |
A comma-separated list of waveform CSV files to be used by the AWG sequencer program. |
|
string |
- |
The target device for AWG sequencer programs upload, e.g. 'dev2006'. |
|
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 |
|
bool |
- |
The index of the current AWG Module to use when running with multiple AWG groups, see HDAWG Channel Grouping for further explanation. |
|
bool |
- |
Enables grouping of multiple synchronized instruments for AWG playback. |
|
int |
- |
The MDS group ( |
Setting/Path | Type | Unit | Description |
---|---|---|---|
|
int |
- |
Compilation status:
|
|
string |
- |
Status message of the compiler. |
|
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:
|
|
int |
- |
Status of the ELF file upload:
|
|
int |
- |
The checksum of the generated ELF file. |
|
double |
- |
Reports the progress of the upload as a value between 0 and 1. |