Spanish Acquisition¶

Subdevices¶

A device which has several versions of the same resources will typically have these resources organized into a tree of subdevices.

For example, an oscilloscope may have multiple input channels, with each having the same set of settings (eg. vertical scaling and offset). These channels may then be viewed as subdevices, and each will have its own values for all its settings.

Mock¶

Mock devices are software simulations of hardware devices. They are typically created at the same time as the device interface and support the same functionality. Most of the time, they are used for testing or as a virtual device.

Output variables¶

Output variables provide a way to sweep over a range of values on a resource. An output variable will have a customizable range of values over which it iterates.

Input variables¶

Typically referred to as “measurements”, input variables provide a way of gathering data from resources.

There exist two types of measurements: scalar and list. Scalar measurements correspond to the acquisition of single values over time (eg. an amplitude or a frequency); list measurements correspond to the acquisition of a list of values over time (eg. a waveform captured by an oscilloscope). Naturally, if the measurements are done several times, scalar measurements produce one-dimensional data, while list measurements produce two-dimensional data.

Plotting options¶

Combinations of scalar columns can be plotted in two or three dimensions, with the “Curve...”, “Colormapped...”, and “Surface...” menu options. These correspond to the Two-dimensional plot, Colormapped plot, and Surface plot.

List columns can be plotted in three dimensions with the “Waveforms...” menu option, which corresponds to the Surface plot in Waveform style.

Class hierarchy¶

All device classes inherit from spacq.devices.abstract_device.AbstractDevice, which provides all the functionality necessary to make connections to physical devices. Subdevices inherit from spacq.devices.abstract_device.AbstractSubdevice. Each device class has its own test class, as well as a mock implementation.

spacq.devices.config.DeviceConfig and spacq.devices.config.device_tree() provide a way to find existing devices and connect to them.

Device implementation notes¶

Testing¶

All the device interfaces can be tested against real hardware as long as the hardware is present and configured.

Configuration of external resources should be done by copying and editing the example file:

cp test-config.py ~/.spacq-test-config.py

File structure¶

Each manufacturer has its own directory in spacq/devices/ (eg. agilent for Agilent, tektronix for Tektronix, etc), and each of these directories may contain any number of devices. There should be at least four files [1] per device:

1. The device interface (eg. dm34410a.py).
2. Tests for the device interface (eg. test_dm34410a.py).
3. A mock implementation of the device (eg. mock_dm34410a.py).
4. A wrapper to run the device tests against the mock (eg. test_mock_dm34410a.py).

Footnotes

cp -r spacq/devices/sample spacq/devices/oxford
vim spacq/devices/oxford/__init__.py # Change the name to "Oxford Instruments".
vim spacq/devices/__init__.py # Add "oxford".

Synchronization¶

To allow for consistent state while performing device commands, each device contains a re-entrant lock. Every read and write operation acquires this lock; thus, multiple reads and writes are mutually excluded. In order to provide a similar mechanism for user-defined methods, the spacq.tool.box.Synchronized decorator can be used. This decorator will acquire the device lock, ensuring that other concurrently-executing threads cannot do the same, and that the atomicity of the decorated method is guaranteed for a given device instance.

Graphical configuration¶

In the case that a device requires a graphical configuration panel, one can be added in the form of a non-modal wxPython dialog (inherited from Dialog). The dialog should reside in spacq/devices/<manufacturer>/gui/<model>.py, and its constructor must take the following arguments, in order:

1. The parent window.
2. The global store.
3. The device name as used in the global store.

The latter two values allow the dialog to find a reference to the device object itself.

In order to announce that a GUI configuration panel is available, the device class (child of AbstractDevice) must have a _gui_setup property which follows the following template:

@property
def _gui_setup(self):
    try:
        from .gui.model import ModelSettingsDialog

        return ModelSettingsDialog
    except ImportError as e:
        log.debug('Could not load GUI setup for device "{0}": {1}'.format(self.name, str(e)))

        return None

Class hierarchy¶

The entire GUI framework is built on wxPython, so all widget classes ultimately inherit from a wxPython class, such as wx.Frame, wx.Panel, or wx.Dialog.

The global store provides spacq.gui.global_store.GlobalStore, a container for the spacq-related global state for an entire application. It includes separate namespaces for devices, resources, and variables, as well as a single slot for a pulse program.

The GUI toolbox provides several GUI primitives which appear frequently, such as a spacq.gui.tool.box.MessageDialog and functions for saving and loading Python-pickled and CSV files with a graphical dialog.

File structure¶

The files are laid out in the same fashion as shown in the Graphical user interface section of the User’s Guide: they are first sorted based on the fundamental type of widget described in the file. Within that, some widgets may be classified futher to restrict them to their own namespace. For example, the plots are found in spacq/gui/display/plot/ rather than just in spacq/gui/display/.

An attempt has been made to keep as much logic as possible out of the GUI code. For example, spacq.gui.action.data_capture.DataCaptureDialog only handles the progress widget, user interaction, and error messages; however, it inherits from spacq.iteration.sweep.SweepController, which handles all the sweep logic. The former is not easily testable, but the latter is tested in spacq.iteration.tests.test_sweep.SweepControllerTest.

Conventions¶

def __init__(self, parent, ..., *args, **kwargs):
    ...
    self.Bind(wx.EVT_BUTTON, self.OnOk, ok_button)
    ...

def OnOk(self, evt=None):
    if self.ok_callback(self):
        self.Destroy()

def OnAction(self, evt=None):
    var = ...

    def ok_callback(dlg):
        try:
            values = dlg.GetValue()
        except ValueError as e:
            MessageDialog(self, str(e), 'Invalid value').Show()
            return False

        var.a, var.b = values

        return True

    dlg = SomeDialog(self, ok_callback)
    dlg.SetValue(var.a, var.b)
    dlg.Show()

pub.subscribe(self.msg_data_capture_start, 'data_capture.start')

pub.sendMessage('data_capture.start', name=name)

def msg_data_capture_start(self, name):
    ...

Thread safety¶

When performing an action which affects the GUI in another thread, it is crucial to use wx.CallAfter. Peforming the action directly, as in:

self.display_label.SetValue('value')

will cause the GUI event loop to break non-deterministically; depending on the frequency of such calls, the app may freeze or crash within a short time, or may not do so at all. To avoid this, the above example would be rewritten as:

wx.CallAfter(self.display_label.SetValue, 'value')

Pulse programs¶

The code for dealing with pulse programs is composed of:

• a parser (spacq.interface.pulse.parser.Parser),
• an AST (spacq.interface.pulse.tree.ASTNode),
• an environment (spacq.interface.pulse.tree.Environment), and
• a presentation wrapper (spacq.interface.pulse.program.Program).

The details of pulse program handling are hidden behind the Program interface, which handles every step of a pulse program’s life cycle from parsing to execution.

When presented with the textual representation of a pulse program, the parser does its best to tranform it into an abstract syntax tree; if it cannot do so, it raises a spacq.interface.pulse.paser.PulseSyntaxError.

Once an AST is obtained, an empty Environment is created. The nodes of the AST are then visited with the Environment over several stages. These stages are:

1. declarations:
   • Populate the environment with the variable declarations.
   • Verify that the declarations make sense.
2. values:
   • Populate the environment with the value assignments.
   • Verify that the assigned values match the declared variables.
3. commands:
   • Verify that all the commands make sense given the collected declarations and values.
4. waveforms:
   • Based on all the collected information, generate the output waveforms.

Resources¶

Units¶

Waveform generation¶

spacq.interface.waveform.Generator provides a mechanism for generating spacq.interface.waveform.Waveform objects. Each Generator will generate a single waveform as its methods are called; after the waveform is complete, it can be obtained via the waveform attribute.

File structure¶

The package consists of only two modules: spacq.iteration.sweep which contains SweepController, and spacq.iteration.variables which defines input and output variables. Together, these modules can be used to provide iteration over a set of variables.

Sweeping¶

spacq.iteration.sweep.SweepController goes through a process of several stages, as crudely drawn in its docstring:

init -> next -> transition -> write -> dwell -> pulse -> read -> ramp_down -> end
^       ^                                  |_____________^  |            |
|       |___________________________________________________|            |
|________________________________________________________________________|

The ordering is approximately linear, but with some loops and skips:

• If no pulse program is defined, the pulse stage is skipped.
• If more items remain to be iterated over, read heads to next.
• If the sweep is continuous, ramp_down restarts it instead of finishing it.

Those steps which deal with accessing resources (transition, write, read, ramp_down) do so in parallel, using as many concurrent threading.Thread objects as necessary.

The sweeping process can be interrupted at any time for many reasons; some of these include: user error, device error, and the user pressing the “Cancel” button. In the case that it is interrupted, the sweep simply proceeds to either the ramp_down or the end stage, depending on whether the interruption is fatal. In the case of a fatal interruption, the ramp_down stage cannot be expected to succeed (for example, if writing to a resource failed), so it is skipped.