3. User’s Guide — ESIBD Explorer 0.6 documentation

# 3. User’s Guide

## 3.1. Getting started

To get started, it is recommended to first configure a few essential Settings. Chose your data path, config path and if applicable plugin path. Enable a few devices, scans, and other plugins in the plugin manager. Select which live displays should be visible. Activate the test mode to simulate device communication while you familiarize yourself with the user interface. Record a few scans and inspect the generated file structure and files. Make use of tool tips and integrated documentation (questionmark icons) to learn about the plugins and settings.

## 3.2. User interface overview

By default, the user interface, shown in Fig. 3.1, is structured into five main sections. The tabs on the left contain all controls for Configuration and management including Settings, Explorer, Devices, Scans, and other controls. During and after the measurement, results are displayed using various Displays on the right. The most important signals of any deposition experiment, including the real-time ion-currents, are always visible in a dedicated Live displays on the top. The Device manager is a central interface that allows to control all devices simultaneously. Finally, there is a hidden Console for status messages and advanced features that can be opened from Settings. Users are free to rearrange the user interface by dragging and tearing components. All devices will be disconnected and turned off to leave them in a save state when the software is closed. All numeric inputs can be conveniently adjusted using the arrow keys. All plugins can be detached and rearranged using the float icon or by dragging them inside or out of the main window. All plugins provide basic documentation via the question mark in their toolbar.

Fig. 3.1 ESIBD Explorer user interface. Colored boxes highlight the five main sections. Live displays showing data from several devices. Central device manager. Configuration and management section including settings, file explorer, as well devices, scans and other controls. Displays of supported files including saved and running scans. Console for debugging and plugin development.

## 3.3. Configuration and management

This is the main control section used to define and access most plugin settings, device configurations, and scans.

### 3.3.1. Settings

The settings plugin allows to edit, save, and load all general program and hardware settings. Settings can be edited either directly or using the context menu that opens on right click. Settings are stored in an .ini file which can be edited directly with any text editor if needed. The settings file that is used on startup is automatically generated if it does not exist. Likewise, default values are used for any missing parameters. Setting files can be exported or imported from the user interface. A change log will show which settings have changed after importing. In addition, the plugin manager and console can be opened from here.

#### 3.3.1.1. General settings

The most important parameters are:

Data path

  Defines where measurement files generated by scans or other plugins will be saved.

Config path

  Defines where all settings and plugin configurations are saved to restore them when restarting the software.

Plugin path

  Defines where the software will look for custom plugins to load while starting.

These parameters are saved in the registry and will be restored independent of the .ini file.

Further settings in this section allow to change the resolution used for graphs, change between dark and light mode, and enable the test mode. All device plugins have access to the test mode and should simulate communication if it is active. This is used for development on machines that are not connected to the hardware.

#### 3.3.1.2. Session settings

All results are automatically saved to the Session path (inside Data path), based on the date, time, substrate, ion, session type, and automatically incremented measurement number. This ensures a consistent file structure that makes it easy to find related sessions. The session path is updated automatically when any of its elements is changed and maintained if the program is restarted. If the software is extended for other types of experiments, the components of the session path can be replaced by more appropriate ones.

#### 3.3.1.3. Acquisition settings

This section allows to reduce the number of displayed data points to increase performance. It also allows to chose if data should be restored after a restart.

#### 3.3.1.4. Other settings

Any plugin can define additional settings and add them here in a dedicated section (e.g., see Device settings). Alternatively, plugins can use the same built-in functions to manage settings internally (e.g., see Scan settings).

### 3.3.2. Explorer

The integrated file explorer is used to navigate all results and complementary data. All files can be accessed independently using the operating system file explorer, e.g., when working on a computer where ESIBD Explorer is not installed. However, the integrated explorer connects dedicated Displays to all files that were created with or are supported by ESIBD Explorer. All supported files are preceded with an icon that indicates which plugin will be used to display them. The data path, current session path, and a search bar are accessible directly from here. File system links or shortcuts are supported as well.

The displays were made to simplify data analysis and documentation. They use dedicated and customizable views that allow saving images as files or sending them to the clipboard for sharing or documentation in a lab book. Right clicking supported files opens a context menu that allows to load settings and configurations directly. For example, a scan file does not only contain the scan data, but also allows to inspect and restore all experimental settings used to record it. Note that the context menu only allows to load device values, but the files contain the entire device configuration. To restore the device configuration based on a scan file, import the file from the device toolbar. A double click will open the file in the external default program. Use third party tools like HDFView to view .hdf files independently.

The explorer may also be useful for other applications beyond managing experimental data. For example, if you organize the documentation of the experimental setup in folders following the hierarchy of components and sub components, it allows you to quickly find the corresponding manuals and order numbers. In combination with the Notes plugin, you can add comments to each component that will be displayed automatically as soon as you enter the corresponding folder.

### 3.3.3. Devices

`Devices` are used to handle communication with one or more physical devices, provide controls to configure the device and display live or previously recorded data. There are input devices (sending input from the user to hardware) and output devices (reading outputs from hardware). Note that some input devices may also read back data from hardware to confirm that the user defined values are applied correctly.

The main interface consists of a list of Channels. By default only the physically relevant information is shown. By entering the advanced mode, additional channel parameters can be configured. The configuration can be exported and imported, though once all channels have been setup it is sufficient to only load values which can be done using a file dialog or from the context menu of an appropriate file in the Explorer. After loading the configurations or values, a change log will be available in the Text plugin to quickly identify what has changed. Each device also comes with a display and a live display. The current values can also be plotted to get a quick overview and identify any unusual values.

#### 3.3.3.1. Device settings

Each device adds a section with the following settings to the Settings section.

Interval

  Data acquisition interval in ms.

Interval (measured)

  Measured plot interval in ms. If this deviates multiple times in a row, the number of display points will be reduced and eventually acquisition will be stopped to ensure the application remains responsive.

Max storage

  Maximum amount of storage used to store history in MB.

Max data points

  Maximum number of data points saved per channel, based on max storage. If this is reached, older data will be thinned to allow to keep longer history.

Other

  Additional device specific settings, e.g. COM ports or IP addresses for communication.

### 3.3.4. Channels

A `channel` represents a virtual or real parameter and manages all data and metadata related to that parameter. Each device can only have one type of channel, but channels have dynamic interfaces that allow to account for differences in the physical backend.

Channels provide a consistent and structured interface to inputs and outputs. In the advanced mode, channels can be duplicated, moved, or deleted. You may also edit channels directly in the corresponding .ini file in the config path.

Channels are accessible from any plugin using `getChannelByName()`. This, and other features like linking channels by equations, depends on the usage of unique and descriptive channel names. Please avoid using very short names, and names that are a subset of names of other channels.

The following defines basic channel properties.

Select

  In the advanced mode, this is used to select a channel to be duplicated, moved, or deleted.

Enabled

  If enabled, the channel will communicate with the device.

Name

  Each channel should have a unique name that will be used to link to the channel from other plugins. The same name may be used for an input and an output channel. Warnings will be displayed if a channel name is repeated.

Value

  The value to be applied to or read from the physical channel.

Monitor

  The read back used to confirm a value has been applied correctly.

Min

  Minimal limit for value. Values will be coerced to limits.

Max

  Maximal limit for value. Values will be coerced to limits.

Optimize

  If selected, the value will be included in optimization using the genetic algorithm.

Equation

  The equation is used to determine the value if the channel is not active. For input devices, this can be used simplify the setup by reducing the number of independent parameters. Any input channel from any device can be linked. For output devices this could be used, e.g., to record differences between two channels. There are no special requirements for the format of the equation as long as it evaluates to a valid python expression after replacing the names with the values from the corresponding channels. Take care to avoid circular definitions and non unique names!

Background

  For output channels, background signals can be defined manually or using the set current value as background option in the corresponding live display. Each value will be saved with a corresponding background. Backgrounds can be optionally and temprarily subtracted without loosing the raw data.

Display

  If selected, channel will be shown in the corresponding live display.

Active

  See Equation. If channels are not active, they will only be visible in the advanced mode.

Real

  Real channels correspond to a real physical input or output. A channel that is not real is a virtual channel. It can be used to in combination with equations to create a more intuitive set of parameters for the user. For example, a deflector lens with four elements can be controlled by virtual offset, **up-down, and left-right parameters.

Linewidth

  The linewith is used to highlight the relative importance of channels in the live display.

Color

  The channel color can be used to visually group related channels allowing for easier navigation in a long list of channels. The channel color will also be used for the corresponding graphs in the display and live display.

Other

  Additional device specific channel parameters like ID, COM, Module, ect.

### 3.3.5. Scans

`Scans` are all sort of measurements that record any number of outputs as a function of any number of inputs. The main interface consists of a list of scan settings. Each scan comes with a tailored display optimized for its specific data format. Scan settings can be imported and exported from the scan toolbar, though in most cases it will be sufficient to import them from the context menu of a previously saved scan file in the Explorer. When all settings are defined and all relevant channels are communicating the scan can be started. A scan can be stopped at any time. At the end of a scan the corresponding file will be saved to the session path. The filename is displayed inside the corresponding graph to allow to find the file later based on exported figures. Scan files are saved in the widely used HDF5 file format that allows to keep data and metadata together in a structured binary file. External viewers, such as HDFView, or minimal python scripts based on the h5py package can be used if files need to be accessed externally. Use the context menu of a scan file to create a template plot file using h5py and adjust it to your needs.

#### 3.3.5.1. Scan settings

Notes

  Add specific notes and metadata to the current scan. Will be reset after scan is saved.

Display

  List of output channels. All defined display channels are recorded but only the selected channel is displayed. A corresponding control in the display allows to change which channel is displayed.

Wait

  Wait time between small steps in ms.

Wait long

  Wait time between steps larger than large step in ms.

Large step

  Threshold step size to use longer wait time. This can be useful if the effect of changing the input is delayed or there is a pickup that needs to decay before measuring.

Average

  Time used for averaging in ms.

Scan time

  Estimated scan time based on the other settings.

Channel

  Input channel to be scanned.

From

  Scan will start at this value.

To

  Scan will stop at this value.

Step

  Scan will use this step size.

Other

  Additional scan specific parameters.

### 3.3.6. Genetic algorithm (GA)

This plugin allows to integrate an independently developed genetic algorithm (GA) for automated optimization of signals.23 Multiple input channels can be selected to be included in the optimization. Make sure to choose safe limits for optimized channels and choose appropriate wait and average values to get valid feedback. The performance and reliability of the optimization depends on the stability and reproducibility of the selected output channel. The output channel can be virtual and contain an equation that references many other channels. At the end of the optimization the changed parameters will be shown in the plugin. The initial parameters can always be restored in case the optimization fails.

### 3.3.7. Omni scan

This is the most basic scan which simply records a number of arbitrary output channels as a function of a single arbitrary input channel. When switched to the interactive mode, a slider will appear that allows to set the value of the input channel manually and independent of the scan settings. This may be more intuitive and faster than automated scanning, e.g. when looking for a local maximum.

### 3.3.8. Custom extensions

The minimal code in “examples/Custom.py” demonstrates how to integrate your own custom elements to the ESIBD Explorer. This should be sufficient as long as your code does not requires interaction with any other elements of the ESIBD Explorer. See Plugin development for more information.

### 3.3.9. Custom device extensions

The minimal code in examples/CustomDevice.py is an example of how to integrate a custom device. See Plugin development for more information.

## 3.4. Displays

A variety of displays are implemented and selected automatically by the corresponding plugin or based on the file type. This includes common file types like .txt, .tex, .png, .jpg, .bmp, .gif, .svg, .wav, .mp3, .ogg, .pdf, .h5, .hdf5, .npy, .star, .pdb1, .css, .py, .js, .html, .ini, .bat, and more. Devices and scans will also come with internal display plugins that are tailored to visualize their specific data. Being able to get all required information form these files without switching to external software avoids clutter and allows to keep an eye on the live signals of the experiment while working with complementary information. Graphs are made with matplotlib, pyqtgraph, or both, allowing the user to choose between complementary ways of data representations and interaction.

All build in display plugins may serve as examples for the development of similar plugins for other purposes. See Plugin development for more information.

### 3.4.1. Browser

The Browser is used to display various file formats. In addition, it provides access to the program description and documentation. Finally, it shows the about content of other plugins when clicking on their respective question mark icons.

### 3.4.2. Notes

The Notes plugin can be used to add quick comments to a session or any other folder. The comments are saved in simple text files that are loaded automatically once a folder is opened again. They are intended to complement but not to replace a lab book.

### 3.4.3. Text

The Text plugin may contain additional useful representation of files, even if they are handled by other plugins. In addition, it may contain information such as change logs after loading settings or configurations from file. It also allows to edit and save simple text files.

### 3.4.4. Tree

The Tree plugin gives an overview of the content of .py, .hdf5, and .h5 files. This includes configuration or scan files and even python source code.

### 3.4.5. MS

The MS plugin allows to display simple mass spectra. Clicking on peaks in a charge state series while holding down the Ctrl key provides a quick estimate of charge state and mass, based on minimizing the standard deviation of the mass as a function of possible charge states. The detailed results are shown in the graph, and help to evaluate the quality of the estimate. In most cases you will need to create your own version of this plugin that is inheriting from the built-in version and redefines how data is loaded for your specific data format. See Plugin development for more information.

### 3.4.6. Line

The Line plugin allows to display simple 2D data. It is made to work with simple xy text files with a three line header. In most cases you will need to create your own version of this plugin that is inheriting from the build in version and redefines how data is loaded for your specific data format. See Plugin development for more information.

### 3.4.7. PDB

The PDB plugin allows to display atoms defined in the .pdb and .pdb1 file formats used by the protein data bank. While the visualization is not very sophisticated it may get you started on interacting programmatically with those files.

### 3.4.8. Holo

The Holo plugin was designed to display 3D NumPy arrays such as holograms from low energy electron holography (LEEH).16,17,18 Interactive 3D surface plots with density thresholds allow for efficient visualization of very large files.

## 3.5. Live displays

Live displays show the history of measured data over time. The toolbar provides icons to initialize, start, pause, stop acquisition, optionally subtract backgrounds, or export displayed data to the current session. Data is only collected if the corresponding live display is visible. The length of the displayed history is determined by the display time control in the tool bar.

Frequently updating those plots is typically the computationally most expensive action. Thus you might want to reduce the number of displayed data points in the acquisition settings. This will make sure that the graphs are updated less frequently and select a smaller but consistent subset of data points for a smooth visualization. While PyQtGraph provides its own algorithms for down sampling data (accessible via the context menu), they tend to cause a flicker when updating data.

## 3.6. Device manager

The device manager, by default located below the Live displays, bundles functionality of devices and thus allows to initialize, start, and stop data acquisition from all devices with a single click. Ideally, plugins that control potentially dangerous hardware like power supplies, cryo coolers, or vacuum valves should add a status icon to the instrument manager, so that their status is visible at all times and they can be shut down quickly, even when the corresponding plugin tab is is not selected. Internally, the device manager also serves as a central interface to all data channels, independent of the devices they belong to, making it easy to setup collection of any number of output signals as a function of any number of input signals.

## 3.7. Console

The console should typically not be needed, unless you are a developer or assist in debugging an issue. It is activated from the tool bar of the Settings. Status messages will be logged here. In addition you can also enable writing status messages to a log file, that can be shared with a developer for debugging. All features implemented in the user interface and more can be accessed directly from this console. Use at your own Risk! You can select some commonly used commands directly from the combo box to get started.

## 3.8. ESIBD specific plugins

The following plugins are specific for ESIBD experiments but may be very similar to what is needed for other applications. If you do ESIBD experiments, make sure to get familiar with those plugins, otherwise consider using them as templates for your own custom plugins. See Plugin development for more information.

### 3.8.1. ISEG

Device that contains a list of voltages channels from an ISEG ECH244 power supply. The voltages are monitored and a warning is given if the set potentials are not reached.

### 3.8.2. RBD

Device that contains a list of current channels, each corresponding to a single RBD 9103 picoammeter. The channels show the accumulated charge over time, which is proportional to the number of deposited ions. It can also reveal on which elements ions are lost.

### 3.8.3. Pressure

Device that bundles pressure values form an Edwards TIC and Pfeiffer MaxiGauge into a consistent list of channels. This demonstrates handling of values on a logarithmic scale.

### 3.8.4. Temperature

Device that reads the temperature of a silicon diode sensor via Sunpower CryoTel controller. It allows to switch units between K and °C.

### 3.8.5. Beam

Scan that records the ion-beam current on one electrode as a function of two voltage channels, typically deflectors. The recorded data can be interpolated to enhance the visualization. A 1:1 aspect ratio is used by default, but a variable ratio can be enabled to maximize use of space. The resulting image is used to identify elements like apertures, samples, and detectors. The beam can be moved between those elements by clicking and dragging on the image while holding down the Ctrl key. Limits can be coupled to have the same step size in both directions. Scan limits can be adopted from the figure or centered around the current value, e.g., to zoom in and center on a specific feature.

### 3.8.6. Spectra

This scan shares many features of the Beam scan. The main difference is that it adds the opption to plot the data in the form of multiple spectra instead of a single 2D plot. The spectra can be plotted stacked (Y axis represents value of Y input channel and data of display channel is normalized.) or overlayed (Y axis represents data of display channel and value of Y input channels are indicated in a legend). In addition, the average of all spectra can be displayed. If you want to remeasure the same spectrum several times, consider defining a dummy channel that can be used as an index.

### 3.8.7. Energy

Scan that records the current on one electrode, typically a detector plate, as a function of one potential, typically a retarding grid. The display shows the measured transmission data, a discrete derivative, and a Gaussian fit that reveals beam-energy center and width. The potential on the selected channel can be changed by clicking and dragging on the image while holding down the Ctrl key.

### 3.8.8. Depo

Scan that records the sample current and accumulated charge during deposition. A target charge and current threshold can be defined and a message will be played back when the target has been reached or the current drops below the threshold. The time until completion is estimated based on recent data. As data analysis is decoupled from data acquisition, you can continue to use all other scan modes and optimization while the deposition recording is running.