Sweeper Module

The Sweeper Module allows the user to perform sweeps as in the Sweeper Tab of the LabOne User Interface. In general, the Sweeper can be used to obtain data when measuring a DUT's response to varying (or sweeping) one instrument setting while other instrument settings are kept constant.

Configuring the Sweeper

In this section we briefly describe how to configure the Sweeper Module. See Table 1 for a full list of the Sweeper’s parameters and Table 2 for a description of the Sweeper’s outputs.

Specifying the Instrument Setting to Sweep

The Sweeper’s gridnode parameter, the so-called sweep parameter, specifies the instrument’s setting to be swept, specified as a path to an instrument’s node. This is typically an oscillator frequency in a Frequency Response Analyzer, e.g., /dev123/oscs/0/freq, but a wide range of instrument settings can be chosen, such as a signal output amplitude or a PID controller’s setpoint.

Specifying the Range of Values for the Sweep Parameter

The Sweeper will change the sweep parameter’s value samplecount times within the range of values specified by start and stop. The xmapping parameter specifies whether the spacing between two sequential values in the range is linear (=0) or logarithmic (=1).

Controlling the Scan mode: The Selection of Range Values

The scan parameter defines the order that the values in the specified range are written to the sweep parameter. In sequential scan mode (=0), the sweep parameter’s values change incrementally from smaller to larger values, see Figure 3. In order to scan the sweep parameter’s in the opposite direction, i.e., from larger to smaller values, reverse scan mode (=3) can be used.

In binary scan mode (=1) the first sweep parameter’s value is taken as the value in the middle of the range, then the range is split into two halves and the next two values for the sweeper parameter are the values in the middle of those halves. This process continues until all the values in the range were assigned to the sweeper parameter, see Figure 5. Binary scan mode ensures that the sweep parameter uses values from the entire range near the beginning of a measurement, which allows the user to get feedback quickly about the measurement’s entire range. Since the Sweeper Module is an asynchronous interface, it’s possible to continuously read and plot data whilst the sweep measurement is ongoing and update points in a graph dynamically.

In bidirectional scan mode (=2) the sweeper parameter’s values are first set from smaller to larger values as in sequential mode, but are then set in reverse order from larger to smaller values, see Figure 4. This allows for effects in the sweep parameter to be observed that depend on the order of changes in the sweep parameter’s values.

Controlling how the Sweeper sets the Demodulator’s Time Constant

The bandwidthcontrol parameter specifies which demodulator filter bandwidth (equivalently time constant) the Sweeper should set for the current measurement point. The user can either specify the bandwidth manually (=0), in which case the value of the current demodulator filter’s bandwidth is simply used for all measurement points; specify a fixed bandwidth (=1), specified by bandwidth, for all measurement points; or specify that the Sweeper sets the demodulator’s bandwidth automatically (=2). Note, to use either Fixed or Manual mode, bandwidth must be set to a value > 0 (even though in manual mode it is ignored).

Specifying the Sweeper’s Settling Time

For each change in the sweep parameter that takes effect on the instrument the Sweeper waits before recording measurement data in order to allow the measured signal to settle. This behavior is configured by two parameters in the settling/ branch: settling/time and settling/inaccuracy.

The settling/time parameter specifies the minimum time in seconds to wait before recording measurement data for that sweep point. This can be used to specify to the settling time required by the user’s experimental setup before measuring the response in their system.

The settling/inaccuracy parameter is used to derive the settling time to allow for the lock-in amplifier’s demodulator filter response to settle following a change of value in the sweep parameter. More precisely, the settling/inaccuracy parameter specifies the amount of settling time as the time required to attain the specified remaining proportion [1e-13, 0.1] of an incoming step function. Based upon the value of settling/inaccuracy and the demodulator filter order, the number of demodulator filter time constants to wait is calculated and written to settling/tc (upon calling the module’s execute() command) which can then be read back by the user. See Table 1 for recommended values of settling/inaccuracy. The relationship between settling/inaccuracy and settling/tc is plotted in Figure 1.

The actual amount of time the Sweeper Module will wait after setting a new sweep parameter value before recording measurement data is defined in Equation 1. For a frequency sweep, the settling/inaccuracy parameter will tend to influence the settling time at lower frequencies, whereas settling/time will tend to influence the settling time at higher frequencies.

The settling time ts used by the Sweeper for each measurement point; the amount of time between setting the sweep parameter and recording measurement data is determined by the settling/tc and settling/time (see Equation 1).

\[\begin{equation}\tag{1} t_s = \text{max}(\text{averaging/tc} \times \text{tc} \times \text{sampling_rate}, \text{averaging/sample}) \end{equation}\]

Note, although it is recommended to use settling/inaccuracy, it is still possible to set the settling time via settling/tc instead of settling/inaccuracy (the parameter applied will be simply the last one that is set by the user).

sweeper inaccuracy time constant
Figure 1. A plot showing the values of the Sweeper’s settling/tc as calculated from settling/inaccuracy parameter and their dependency on demodulator order filter.

Specifying which Data to Measure

Which measurement data is actually returned by the Sweeper’s read command is configured by subscribing to node path using the Sweeper Module’s subscribe command.

Specifying how the Measurement Data is Averaged

One Sweeper measurement point is obtained by averaging recorded data which is configured via the parameters in the averaging/ branch.

The averaging/tc parameter specifies the minimum time window in factors of demodulator filter time constants during which samples will be recorded in order to average for one returned sweeper measurement point. The averaging/sample parameter specifies the minimum number of data samples that should be recorded and used for the average. The Sweeper takes both these settings into account for the measurement point’s average according to Equation 2.

The number of samples N used to average one sweeper measurement point is determined by the parameters averaging/tc and averaging/sample (see Equation 2).

\[\begin{equation}\tag{2} N = \text{max}(\text{averaging/tc} \times \text{tc}, \text{sampling_rate}, \text{averaging/sample}) \end{equation}\]

Note, the value of the demodulator filter’s time constant may be controlled by the Sweeper depending on the value of bandwidthcontrol and bandwidth, see the section above called Controlling how the Sweeper sets the Demodulator’s Time Constant . For a frequency sweep, the averaging/tc parameter will tend to influence the number of samples recorded at lower frequencies, whereas averaging/sample will influence averaging behavior at higher frequencies.

An Explanation of Settling and Averaging Times in a Frequency Sweep

Figure 2 shows which demodulator samples are used in order to calculate an averaged measurement point in a frequency sweep. This explanation of the Sweeper’s parameters is specific to the following commonly-used Sweeper settings:

  • gridnode is set to an oscillator frequency, e.g., /dev123/oscs/0/freq.

  • bandwidthcontrol is set to 2, corresponding to automatic bandwidth control, i.e., the Sweeper will set the demodulator’s filter bandwidth settings optimally for each frequency used.

  • scan is set to 0, corresponding to sequential scan mode for the range of frequency values swept, i.e, the frequency is increasing for each measurement point made.

Each one of the three red segments in the demodulator data correspond to the data used to calculate one single Sweeper measurement point. The light blue bars correspond to the time the sweeper should wait as indicated by settling/tc (this is calculated by the Sweeper Module from the specified settling/inaccuracy parameter). The purple bars correspond to the time specified by the settling/time parameter. The sweeper will wait for the maximum of these two times according to Equation 1. When measuring at lower frequencies the Sweeper sets a smaller demodulator filter bandwidth (due to automatic bandwidthcontrol) corresponding to a larger demodulator filter time constant. Therefore, the settling/tc parameter dominates the settling time used by the Sweeper at low frequencies and at high frequencies the settling/time parameter takes effect. Note, that the light blue bars corresponding to the value of settling/tc get shorter for each measurement point (larger frequency used → shorter time constant required), whereas the purple bars corresponding to settling/time stay a constant length for each measurement point. Similarly, the averaging/tc parameter (yellow bars) dominates the Sweeper’s averaging behavior at low frequencies, whereas averaging/samples (green bars) specifies the behavior at higher frequencies, see also Equation 2.

sweeper parameters v4
Figure 2. Plot demonstrating how the Sweeper records three measurement points from demodulator data when using automatic bandwidth control in a frequency sweep. Please see An Explanation of Settling and Averaging Times in a Frequency Sweep, for a detailed explanation.

Average Power and Standard Deviation of the Measured Data

The Sweeper returns measurement data upon calling the Sweeper’s read() function. This returns not only the averaged measured samples (e.g. r) but also their average power (rpwr) and standard deviation (rstddev). In order to obtain reliable values from this statistical data, please ensure that the averaging branch parameters are configured correctly. It’s recommended to use at least a value of 12 for averaging/sample to ensure enough values are used to calculate the standard deviation and 5 for averaging/tc in order to prevent aliasing effects from influencing the result.

Table 1. Sweeper Parameters
Setting/Path Type Unit Description

device

string

-

The device ID to perform the sweep on, e.g., dev123 (compulsory parameter).

gridnode

string

Node

The device parameter (specified by node) to be swept, e.g., "oscs/0/freq".

start

double

Many

The start value of the sweep parameter.

stop

double

Many

The stop value of the sweep parameter.

samplecount

uint64

-

The number of measurement points to set the sweep on.

endless

bool

-

Enable Endless mode; run the sweeper continuously.

remainingtime

double

Seconds

Read only: Reports the remaining time of the current sweep. A valid number is only displayed once the sweeper has been started. An undefined sweep time is indicated as NAN.

averaging/sample

uint64

Samples

Sets the number of data samples per sweeper parameter point that is considered in the measurement. The maximum of this value and averaging/tc is taken as the effective calculation time. See Figure 2.

averaging/tc

double

Seconds

Sets the effective measurement time per sweeper parameter point that is considered in the measurement. The maximum between of this value and averaging/sample is taken as the effective calculation time. See Figure 2.

bandwidthcontrol

uint64

-

Specify how the sweeper should specify the bandwidth of each measurement point, Automatic is recommended, in particular for logarithmic sweeps and assures the whole spectrum is covered.

0

Manual (the sweeper module leaves the demodulator bandwidth settings entirely untouched)

1

Fixed (use the value from bandwidth)

2

Automatic

Note, to use either Fixed or Manual mode, bandwidth must be set to a value > 0 (even though in manual mode it is ignored).

bandwidthoverlap

bool

-

If enabled the bandwidth of a sweep point may overlap with the frequency of neighboring sweep points. The effective bandwidth is only limited by the maximal bandwidth setting and omega suppression. As a result, the bandwidth is independent of the number of sweep points. For frequency response analysis bandwidth overlap should be enabled to achieve maximal sweep speed.

bandwidth

double

Hz

Defines the measurement bandwidth when using Fixed bandwidth mode (bandwidthcontrol=1), and corresponds to the noise equivalent power bandwidth (NEP).

order

uint64

-

Defines the filter roll off to use in Fixed bandwidth mode (bandwidthcontrol=1). Valid values are between 1 (6 dB/octave) and 8 (48 dB/octave).

maxbandwidth

double

Hz

Specifies the maximum bandwidth used when in Auto bandwidth mode (bandwidthcontrol=2) (bandwidthcontrol=2). The default is 1.25 MHz.

omegasuppression

double

dB

Damping of omega and 2omega components when in Auto bandwidth mode (bandwidthcontrol=2). Default is 40dB in favor of sweep speed. Use a higher value for strong offset values or 3omega measurement methods.

loopcount

uint64

-

The number of sweeps to perform.

phaseunwrap

bool

-

Enable unwrapping of slowly changing phase evolutions around the +/-180 degree boundary.

sincfilter

bool

-

Enables the sinc filter if the sweep frequency is below 50 Hz. This will improve the sweep speed at low frequencies as omega components do not need to be suppressed by the normal low pass filter.

scan

uint64

-

Selects the scanning type:

0

Sequential (incremental scanning from start to stop value, see Figure 3).

1

Binary (Non-sequential sweep continues increase of resolution over entire range, see Figure 5).

2

Bidirectional (Sequential sweep from Start to Stop value and back to Start again, Figure 4).

3

Reverse (reverse sequential scanning from stop to start value).

Note, to use either Fixed or Manual mode, bandwidth must be set to a value > 0 (even though in manual mode it is ignored).

settling/time

double

Seconds

Minimum wait time in seconds between setting the new sweep parameter value and the start of the measurement. The maximum between this value and settling/tc is taken as effective settling time. See Figure 2.

settling/inaccuracy

double

-

Demodulator filter settling inaccuracy defining the wait time between a sweep parameter change and recording of the next sweep point. The settling time is calculated as the time required to attain the specified remaining proportion [1e-13, 0.1] of an incoming step function. Typical inaccuracy values: 10m for highest sweep speed for large signals, 100u for precise amplitude measurements, 100n for precise noise measurements. Depending on the order of the demodulator filter the settling inaccuracy will define the number of filter time constants the sweeper has to wait. The maximum between this value and the settling time is taken as wait time until the next sweep point is recorded. The relationship between settling/inaccuracy and settling/tc is plotted in Figure 1.

settling/tc

double

TC

Minimum wait time in factors of the time constant (TC) between setting the new sweep parameter value and the start of the measurement. This filter settling time is preferably configured via the settling/inaccuracy (see discussion in Configuring the Sweeper and Figure 1). The maximum between this value and settling/time is taken as effective settling time. See Figure 2.

xmapping

uint64

-

Selects the spacing of the grid used by gridnode (the sweep parameter):

0

linear

1

logarithmic

distribution of sweep parameter values.

historylength

uint64

Maximum number of entries stored in the measurement history.

clearhistory

bool

-

Remove all records from the history list.

directory

string

-

The directory to which sweeper measurements are saved to via save().

savepath

string

-

This parameter is deprecated, see directory.

fileformat

string

-

The format of the file for saving sweeper measurements.

0

Matlab.

1

CSV.

2

ZView (for impedance measurements only).

3

SXM (image format).

4

HDF5.

sequential scan2
Figure 3. Sweeper scanning modes: Sequential (scan = 0).
bidirect
Figure 4. Sweeper scanning modes: Bidirectional (scan = 2).
bin scan2
Figure 5. Sweeper scanning modes: Binary (scan = 1).
Table 2. Sweeper Output Values
Name Type Unit Description

auxin0

double

Volts

Auxiliary Input 1 value.

auxin1

double

Volts

Auxiliary Input 2 value.

auxin0pwr

double

Volts2

Average power of Auxiliary Input 1 value.

auxin1pwr

double

Volts2

Average power of Auxiliary Input 2 value.

auxin0stddev

double

Volts

Standard deviation of Auxiliary Input 1 value.

auxin1stddev

double

Volts

Standard deviation of Auxiliary Input 2 value.

frequency

double

Hz

The oscillator frequency for each measurement point (for a frequency sweep this is the same as grid).

frequencypwr

double

Hz2

Average power of the oscillator frequency.

frequencystddev

double

Hz

Standard deviation of the oscillator frequency.

phase

double

Radians

Demodulator phase value.

phasestddev

double

Radians

Standard deviation of demodulator phase value (phase noise).

phaserpwr

double

Radians2

Average power of demodulator phase value (phase noise).

r

double

VoltsRMS

Demodulator R value.

rstddev

double

VoltsRMS

Standard deviation of demodulator R value.

rpwr

double

Volts2

Average power of demodulator x value.

x

double

Volts

Demodulator x value.

xstddev

double

Volts

Standard deviation of demodulator x value.

xpwr

double

Volts2

Average power of demodulator x value.

y

double

Volts

Demodulator y value.

ystddev

double

Volts

Standard deviation of demodulator y value.

ypwr

double

Volts2

Average power of demodulator y value.

bandwidth

double

Hz

Demodulator filter’s bandwidth as calculated from tc (if performing a frequency sweep).

bandwidthmode

integer

-

The value of the bandwidthcontrol used for the sweep.

count

integer

-

The number of measurement points actually used by the sweeper when averaging the data. This depends on the values of the parameters in the averaging/ branch.

grid

double

Many

Values of sweeping setting (frequency values at which demodulator samples where recorded).

flags

integer

-

Reserved for future use.

settling

double

Seconds

The waiting time for each measurement point.

samplecount

uint64

-

The number of swept measurement points (the value of samplecount).

sampleformat

integer

-

Reserved for future use.

sweepmode

integer

-

The value of the scan used for the sweep.

tc

double

Seconds

Demodulator’s filter time constant as set for each measurement point.

tcmeas

double

Seconds

Reserved for future use.

timestamp

uint64

Ticks

A timestamp that gets updated each time a new measurement point has been recorded by the sweeper (divide by the device’s clockbase to obtain seconds). It is not part of the sweeper’s measurement data and only relevant for intermediate reads of sweeper data (before the current sweep has finished).

settimestamp

uint64

Ticks

The timestamp at which we verify that the frequency for the current measurement point was set on the device (by reading back demodulator data).

nexttimestamp

uint64

Ticks

The timestamp at which we can obtain the data for that measurement point, i.e., nexttimestamp - settimestamp corresponds roughly to the demodulator filter settling time.