Table Of Contents

Previous topic

File formats

Next topic

Scan event example

This Page

Developer’s guide

This section addresses to those who want to extend TeraPy with additional features. TeraPy is built on a modular (plug-in) concept, which allows you to add features without digging much into the core package.

TeraPy’s architecture is articulated around specific data structures, which are exchanged between processes. These data structures are reviewed first.

The components that can be extended by plug-ins are reviewed afterwards.

Data structures

In TeraPy, data are handled primarily through the DataArray class. TeraPy modules talk to each other with DataArray objects. During measurement, a Measurement class object is used to facilitate the process. A graphical overview of how this works is shown below. Items with a red background can be extended by plug-ins.

_images/flowchart.png

Data management in TeraPy

Measurement class object

A Measurement class object is created upon execution of a scan sequence. It contains one DataArray class object for each measurement event (i.e. each event that reads data). The Measurement class comes with several functions, designed to facilitate the measurement process. These are:

  • IncrementScanDimension / DecrementScanDimension / SetScanDimension / GetScanDimension: control the dimension, which is currently scanned.
  • ResetCounter: reset position counters for every scan dimension.
  • Increment / Decrement / SetScanPosition / GetScanPosition: control the position for the current scan dimension.
  • SetCoordinateValue / GetCoordinateValue: set/get the coordinate value for the current dimension.
  • SetCurrentValue / GetCurrentValue: set/get the data value for the current scan position.

You will find detailed informations on these functions in the terapy_core_dataman documentation.

DataArray class object

A DataArray object contains the actual measurement data and the associated coordinate vectors. The DataArray class comes with some functions used during the measurement process. These are:

  • Increment / Decrement / SetPosition / GetPosition: control position counter.
  • SetCoordinateValue / GetCoordinateValue: set/get coordinate value.
  • SetValue / GetValue: set/get data value.

Detailed informations can be found in the terapy_core_dataman documentation.

Plug-in architecture

TeraPy’s architecture is plug-in-based. Provided that a few guidelines are followed, custom modules placed in the module_path folder (see Main configuration settings) will be automatically recognized as new features. Alternatively, you can also drop your file in the relevant TeraPy subpackage (you may do that if you want your extension to be accessible system-wide).

The parts of TeraPy that can be extended by plug-ins are detailed below.

Scan events

Scan events are actions that will be performed within a measurement sequence. TeraPy recognizes several event types:

  • Sequence: is_root = True. A sequence encloses a set of scan events. It is a root event, and therefore cannot be included as a child of another event.
  • Loop: is_loop = True. A loop event can host children events, which will be run on each loop iteration.
  • Measurement: is_input = True. A measurement event reads from a source and records the value to a DataArray object.
  • Save: is_save = True. A save event sends data to some sink (file, printer, ...).
  • Display: is_display = True. a display event is meant to display data. It will most likely interact with a plot canvas within TeraPy’s interface.

For now, these properties are mutually exclusive (a scan event can be of one kind only).

A class is recognized as a scan event if it is a subclass of terapy.scan.base.ScanEvent. See Scan event example for details. You can also find informations and further examples in the terapy.scan package documentation.

Post-processing filters

Post-processing filters are classes that provide data processing functions. One post-processing filter is designed for one given dimension (set by the dim class constant). The filter takes a DataArray object and processes its content in place. When adding post-processing canvases, TeraPy automatically makes a copy of the source data to be processed. You don’t have to worry about this yourself.

TeraPy recognizes several filter types:

  • Pre-transform: is_pre_filter = True. This filter will only be applied before a domain transform (e.g. Fourier transform). Currently, this is used to compute the apodization window preview (see user interface guide Post-processing filters section).
  • Transform: is_transform = True. This filter is a domain transform (e.g. Fourier transform).
  • Reference: is_reference = True. This filter takes some data and uses it as a reference for further computation (e.g. normalization).

These properties are optional and mutually exclusive (only one can be set to True).

A class is recognized as a post-processing filter if it is a subclass of terapy.filters.base.Filter. See Post-processing filter example for details. You can also find informations and further examples in the terapy.filters package documentation.

File format filters

File format filters are classes that enable reading from and/or saving to some data format. Such a filter can have the following capabilities:

  • Read: can_read = True. Indicates that this filter can read data from a file and compile a DataArray object out of it.
  • Save: can_save = True. Indicates that this filter can take a DataArray object and save its content to one or several files.
  • Multiple datasets: multi_data = True. If this is set, the filter must be able to save more than one DataArray in one single file.

Presently, TeraPy lets the filter check that it can handle the shape of the provided data array.

A class is recognized as a file format filter if it is a subclass of terapy.files.base.FileFilter. See File format filter example for details. You can also find informations and further examples in the terapy.files package documentation.

Plot canvases and plots

Plot canvases and plots are responsible for data display. When a display request is issued, TeraPy looks for a canvas capable of displaying the data. One canvas type can handle one data dimension and must have one associated plot type. The reason why we make a distinction between canvas and plots is that some canvases can host more than one plot, and some don’t. However, a DataArray object can only be plotted once, and therefore will be linked with a Plot object (and not a PlotCanvas).

A plot canvas must be of one of two types:

  • Data canvas: is_data = True. The canvas can plot raw data only (no post-processing).
  • Post-processing canvas: is_filter = True. The canvas can plot post-processed data only. In TeraPy’s interface, it will be made child of a data canvas or another post-processing canvas (nested post-processing).

A class is recognized as a plot canvas if it is a subclass of terapy.plot.base.PlotCanvas. See Plot canvas example for details. Likewise, a class is recognized as a plot if it is a subclass of terapy.plot.base.Plot. See Plot example for details. You can also find informations and further examples in the terapy.plot package documentation.

Devices

Primarily, device drivers provide an access to devices for scan events. They can (optionally) add widgets that will be displayed in the user interface (see Device widgets to learn where).

Currently, two types of devices are recognized:

Input devices

A driver for an input device has essentially one function: read data. It is expected to read one or several data points and return them as a list of floating point numbers.

A class will be recognized as an input device driver if it is a subclass of terapy.hardware.input.base.InputDevice. See Input device driver example for details. You can also find informations and further examples in the terapy.hardware.input package documentation.

Axis devices

A driver for an axis device is meant to set the value of some device parameter. One driver instance can only set one quantity at a time. Axis device drivers where primarily meant to control mechanical stages (hence the name), but they are not limited to that either (changing voltage on a power supply or temperature on a temperature controller works equally well).

A class will be recognized as an axis device driver if it is a subclass of terapy.hardware.axes.base.AxisDevice. See Axis device driver example for details. You can also find informations and further examples in the terapy.hardware.axes package documentation.