Accessing Variables in Python User-Operator Scripts
Input Variables
When FlexDCA starts a user-operator script, the following variables are passed to the script as key:value pairs in a dictionary. Any variables that you defined with the <Variable> XML element are also passed to the script as well as any user-defined control variables that you defined with the <Integer>, <Double>, <Enumeration>, <String>, or <File> XML elements. For example, your script will start with the function definition shown below. The input variables are passes in the variables dictionary. In the second line, the function uses the SrcData dictionary key to assign the value which is the input waveform to the SrcData variable.
def algorithm(variables):
SrcData = variables['SrcData']
…
…
In your script, you can print the output variables to the Show Output window as demonstrated in Lesson 2 and explained in Troubleshooting Python scripts.
Each input variables, except SoftwareVersion, listed in the following table has two forms. The one listed is for a single input waveform or the waveform 1 of a dual-waveform input measurement. If a second input waveform exists, its variable has the digit "2" appended. For example, SrcData becomes SrcData2 for the second waveform.
| Dictionary keys | Type | Description | |
|---|---|---|---|
| SrcData | numpy.ndarray | The input waveform.
Values are in volts for electrical signals and Watts for optical signals. Example key: value pair: 'SrcData': array([-2.24755, -0.246670, -0.251945, …, 0.24080, 0.24792, 0.2524]) |
|
| Source | string | The source of the input waveform. Example key: value pair: 'Source': 'Channel 1B' |
|
| SourceBw | float | The bandwidth of the input source. Example key: value pair: 'SourceBw': 150000000000.0 |
|
| XOrg | float | The time of the first x-axis value of the input waveform value of SrcData. Example key: value pair: 'XOrg': 8.785e-11 |
|
| XInc | float | The spacing of the x-axis input waveform values of SrcData. Example key: value pair: 'XInc': 2.232e-13 |
|
| XUnits | string | The X units associated with the input waveform. Refer to Valid Measurement Units. Example key: value pair: 'XUnits': 'Second' |
|
| YUnits | string | The Y units associated with the input waveform. Refer to Valid Measurement Units. Example key: value pair: 'YUnits': 'Volt' |
|
| BitRate | float | FlexDCA A.05.61 and below. Deprecated in FlexDCA A.05.62 and above. Use the recommended SymbolRate variable instead.
The current value of the 'Data Rate' control in the pattern lock tab of the trigger setup dialog. If pattern lock is not turned on, this value may not be correct. Example key: value pair: 'BitRate': 9953280000.0 |
|
| SymbolRate | float | Available FlexDCA A.05.62 and above.
The current value of the 'SymbolRate' control in the pattern lock tab of the trigger setup dialog. If pattern lock is not turned on, this value may not be correct. Example key: value pair: 'SymbolRate': 9953280000.0 |
|
| PatLength | integer | The current value of the 'Pattern Length' control in the pattern lock tap of the trigger setup dialog. If pattern lock is not turned on, this value may not be correct. Example key: value pair: 'PatLength': 127 |
|
| SrcClipped | bolean | Set to True if the source data was clipped high or low; otherwise set to False. Example key: value pair: 'SrcClipped': True |
|
| ClipHigh | float | The maximum value that could be present in the source waveform. If SrcClipped is True, check to see which elements of SrcData are equal to ClipHigh to determine which elements were clipped. Example key: value pair: 'ClipHigh': 0.51057 |
|
| ClipLow | float | The minimum value that could be present in the source waveform. If SrcClipped is True, check to see which elements of SrcData are equal to ClipLow to determine which elements were clipped. Example key: value pair: 'ClipLow': -0.510869 |
|
| IsAvgComplete | bolean | Flag tells if waveform averaging is complete. Set to True if complete, otherwise False if not complete. Example key: value pair: 'IsAvgComplete': True |
|
| IsPeriodic | bolean | Flag tells if waveform is periodic. Set to True if complete, otherwise False if not complete. Example key: value pair: 'IsPeriodic': False |
|
| AvgAcqCount | long | The current value of the 'Number of Averages' control in the Averaging tab of the Acquistion dialog if averaging is enabled, otherwise its value is 1. The value is an unsigned long integer in Python 2. Example key: value pair: 'AvgAcqCount': 1L |
|
| Markers | list of dictionaries | Marker information if markers are on source waveform. If a marker is not on, it is not included in the list. | |
Example key: value pair:
'Markers': [
{'Status': 'Correct','Source': 'Channel 1B','Name': 'X1,'Position': 1.01033e-10},
{'Status': 'Correct','Source': 'Channel 1B','Name': 'X2,'Position': 1.28445e-10},
{'Status': 'Correct','Source': 'Channel 1B','Name': 'X3,'Position': 1.50625e-10},
{'Status': 'Correct','Source': 'Channel 1B','Name': 'X4,'Position': 1.78664e-10}]
|
|||
| TdrAmplitude | float | The current amplitude of the TDR waveform. | |
| TdrPolarity | string | The current polarity of the TDR waveform. | |
| TdrRiseTime | float | The current rise time of the TDR waveform. | |
| DielectricConstant | float | The dielectric constant of the TDR waveform. (If horizontal units are defined in distance instead of time.) | |
| VelocityFactor | float | The velocity factor of the TDR waveform. (If horizontal units are defined in distance instead of time.) | |
| SoftwareVersion | string | The FlexDCA software version that is being run. | |
Output Variables
This topic lists the variables whose values are returned to FlexDCA when your script completes. The top three variables listed in the table must be set in your script. The remaining variables may be used, if needed.
| Variable | Type | Description |
|---|---|---|
| Variables that must be returned by your script | ||
| FiltData | list | Output waveform. |
| XInc | float | The spacing of the x-axis values of FiltData. |
| XOrg | float | The time of the first x-axis value of FiltData. |
| Optional variables that can be returned by your script | ||
| ErrorMsg | string | Any generated FlexDCA error message. |
| FilterDelay | float | Filter delay. |
| FilterWidth | float | Filter width. |
| Gain | float | Signal gain of operators that have one input. |
| Gain2 | float | Signal gain of operators that have two inputs. |
| XUnits | string | The X units associated with the output waveform's x-axis. Refer to Valid Measurement Units. |
| YUnits | string | The Y units associated with the output waveform's y-axis. Refer to Valid Measurement Units. |