.. include:: icons.rst .. _`sec:UsersGuide`: User's Guide ============ Getting started --------------- To get started, it is recommended to first configure a few essential :ref:`sec:settings`. Chose your :ref:`data path`, :ref:`config path` and if applicable :ref:`plugin path`. Enable a few devices, scans, and other plugins in the plugin manager dialog |pluginDialog| found under :ref:`sec:settings` |settings|. Select which live displays should be visible |system-monitor|. Activate the test mode (active by default) 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 tooltips and integrated documentation (question mark icons |help|) to learn about the plugins and their settings. User interface overview ----------------------- By default, the user interface, shown in :numref:`fig:overview`, is structured into five main sections. The tabs on the left contain all controls for configuration and management including :ref:`sec:settings` |settings|, :ref:`sec:explorer` |explorer|, :ref:`sec:devices`, :ref:`sec:scans`, and other controls. During and after the measurement, results are displayed using various :ref:`sec:displays` on the right. The most important signals of any deposition experiment, including the real-time ion-currents, are always visible in a dedicated :ref:`sec:live_displays` on the top. The :ref:`sec:deviceManager` |deviceManager| is a central interface that allows to control all devices simultaneously. Finally, there is a :ref:`sec:console` |console| for status messages and advanced features that can be opened from :ref:`sec:settings` |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 provide basic documentation via the question mark |help| in their toolbar. .. _`fig:overview`: .. figure:: 2023-10_ESIBD_GUI.png :width: 100% **ESIBD Explorer user interface.** Colored boxes highlight the five main sections. :blue:`Live displays` showing data from several devices. Central :darkorange:`device manager`. :red:`Configuration and management` section including settings, file explorer, as well devices, scans and other controls. :orange:`Displays` of supported files including saved and running scans. :green:`Console` for debugging and plugin development. .. _`fig:overview_video`: .. video:: 2025-02_ESIBD_GUI.mp4 :width: 100% :align: center :caption: This video was created as part of automated testing and shows many plugins and their interactions. Simulated mouse clicks are indicated by blue circles. While this cannot replace a structured video tutorial, it gives a better idea about what to expect before installing ESIBD Explorer. .. _`sec:settings`: |settings| Settings ------------------- .. automodule:: esibd.plugins.Settings :noindex: General settings ~~~~~~~~~~~~~~~~ The most important parameters are: .. _`data_path`: Data path Defines where measurement files generated by scans or other plugins will be saved. .. _`config_path`: Config path Defines where all settings and plugin configurations are saved to restore them when restarting the software. .. _`plugin_path`: 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. .. _`sec:session_settings`: 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. .. _`sec:acquisition_settings`: 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. Other settings ~~~~~~~~~~~~~~ Any plugin can define additional settings and add them here in a dedicated section (e.g., see :ref:`sec:device_settings`). Alternatively, plugins can use the same built-in functions to manage settings internally (e.g., see :ref:`sec:scan_settings`). .. _`sec:explorer`: |explorer| Explorer ------------------- .. automodule:: esibd.plugins.Explorer :noindex: .. _`sec:ucm`: |ucm| UCM --------- .. automodule:: esibd.plugins.UCM :noindex: .. _`sec:PID`: |pid| PID --------- .. automodule:: esibd.plugins.PID :noindex: .. _`sec:devices`: Devices ------- .. automodule:: esibd.plugins.Device :noindex: .. _`sec:device_settings`: Device settings ~~~~~~~~~~~~~~~ Each device adds a section with the following settings to the :ref:`sec:settings` section. .. _`acquisition_interval`: 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. .. _`sec:calculator`: |calculator| Calculator ~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: esibd.examples.calculator.calculator_plugin.Calculator :noindex: .. _`sec:customDevice`: |customDevice| Custom device ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: esibd.examples.custom_device.custom_device.CustomDevice :noindex: .. _`sec:customDevice2`: |customDevice2| Custom device 2 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: esibd.examples.custom_device.custom_device2.CustomDevice2 :noindex: .. _`sec:ISEG`: |iseg| ISEG ~~~~~~~~~~~ .. automodule:: esibd.devices.iseg.iseg.ISEG :noindex: .. _`sec:KEITHLEY`: |keithley| KEITHLEY ~~~~~~~~~~~~~~~~~~~ .. automodule:: esibd.devices.keithley.keithley.KEITHLEY :noindex: .. _`sec:LS335`: |ls335| LS335 ~~~~~~~~~~~~~ .. automodule:: esibd.devices.lakeshore335.lakeshore.LS335 :noindex: .. _`sec:MAXIGAUGE`: |maxigauge| MAXIGAUGE ~~~~~~~~~~~~~~~~~~~~~ .. automodule:: esibd.devices.maxigauge.maxigauge.MAXIGAUGE :noindex: .. _`sec:MIPS`: |mips| MIPS ~~~~~~~~~~~ .. automodule:: esibd.devices.mips.mips.MIPS :noindex: .. _`sec:ni9263`: |ni9263| NI9263 ~~~~~~~~~~~~~~~ .. automodule:: esibd.devices.ni9263.ni9263.NI9263 :noindex: .. _`sec:OMNICONTROL`: |omnicontrol| OMNICONTROL ~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: esibd.devices.omnicontrol.omnicontrol.OMNICONTROL :noindex: .. _`sec:PICO`: |pico| PICO ~~~~~~~~~~~ .. automodule:: esibd.devices.pico.pico.PICO :noindex: .. _`sec:RBD`: |rbd| RBD ~~~~~~~~~ .. automodule:: esibd.devices.rbd.rbd.RBD :noindex: .. _`sec:RSPD3303C`: |rspd3303c| RSPD3303C ~~~~~~~~~~~~~~~~~~~~~ .. automodule:: esibd.devices.rspd3303c.rspd3303c.RSPD3303C :noindex: .. _`sec:SPA`: |spa| SPA ~~~~~~~~~ .. automodule:: esibd.devices.spa.spa.SPA1x0 :noindex: .. _`sec:Temperature`: |temperature| Temperature ~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: esibd.devices.temperature.temperature.Temperature :noindex: .. _`sec:TIC`: |tic| TIC ~~~~~~~~~ .. automodule:: esibd.devices.tic.tic.TIC :noindex: .. _`sec:webcam`: |webcam| Webcam ~~~~~~~~~~~~~~~ .. automodule:: esibd.controls.webcam.webcam.Webcam :noindex: .. _`sec:channels`: Channels -------- .. automodule:: esibd.core.Channel :noindex: 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 and :ref:`real`, the channel will communicate with the physical 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. .. _`equation`: Equation The equation is used to determine the value if the channel is not active. For input devices, this can be used to simplify the setup by reducing the number of independent parameters. Any input channel from any device can be referenced. 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! If the equation is empty it will be ignored. Background For output channels, background signals can be defined manually or using the *set current value as background* option in the corresponding :ref:`live display`. Each value will be saved with a corresponding background. Backgrounds can be optionally and temporarily subtracted without loosing the raw data. Optimize If selected, the value will be included in optimization using the :ref:`genetic algorithm`. Display If selected, channel will be shown in the corresponding :ref:`live display`. Active See :ref:`equation` and :ref:`real`. .. _`real`: 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 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. If a channel is active and real, the value will be requested from or send to the physical device. This is the default. If a channel is active and not real, the value will not be updated. Use this e.g. to define a fixed offset. If a channel is not active and real, the value will be determined by the equation and send to the physical device (if it accepts inputs). Use this e.g. to add a fixed offset before sending the value to a physical device. Note that monitors (readbacks) will still be read, even if the channel is not active. If a channel is not active and not real, the value will be determined by the equation. Use this e.g. for calculations with intermediate steps or just to display the result of an equation. Line width The line width is used to highlight the relative importance of channels in the :ref:`live display`. Line style The line style is used to further distinguish channels with similar color in the :ref:`live display`. Group :ref:`Live displays` allow channels to be grouped by this parameter. This allows to group channels with different units and define the order in which they appear in the :ref:`live display`. Scaling Scale channels to highlight importance and see them from the other side of the lab. 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 :ref:`display` and :ref:`live display`. Other Additional device specific channel parameters like *ID*, *COM*, *Module*, ect. .. _`sec:scans`: Scans ----- .. automodule:: esibd.plugins.Scan :noindex: .. _`sec:scan_settings`: 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 :ref:`large step` in ms. .. _`large_step`: 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. .. _`sec:genetic_algorithm`: |ga| Genetic algorithm (GA) ~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: esibd.scans.ga.ga.GAScan :noindex: .. _`sec:omni`: |omni| Omni scan ~~~~~~~~~~~~~~~~ .. automodule:: esibd.scans.omni.omni.Omni :noindex: .. _`sec:spectra`: |spectra| Spectra scan ~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: esibd.scans.spectra.spectra.Spectra :noindex: The following scans are used for ESIBD experiments but may be very similar or identical to what is needed for other applications. If you do ESIBD experiments, make sure to get familiar with those scans, otherwise consider using them as templates for your own custom scans. See :ref:`sec:plugin_system` for more information. .. _`sec:beam`: |beam| Beam scan ~~~~~~~~~~~~~~~~ .. automodule:: esibd.scans.beam.beam.Beam :noindex: .. _`sec:energy`: |energy| Energy scan ~~~~~~~~~~~~~~~~~~~~ .. automodule:: esibd.scans.energy.energy.Energy :noindex: .. _`sec:depo`: |depo| Depo scan ~~~~~~~~~~~~~~~~ .. automodule:: esibd.scans.depo.depo.Depo :noindex: Custom extensions ----------------- .. automodule:: esibd.examples.custom_plugin.custom_plugin.CustomPlugin :noindex: .. _sec:displays: 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. :ref:`sec:devices` and :ref:`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 :ref:`sec:plugin_system` for more information. .. _`sec:browser`: |browser| Browser ~~~~~~~~~~~~~~~~~ .. automodule:: esibd.plugins.Browser :noindex: .. _`sec:notes`: |notes| Notes ~~~~~~~~~~~~~ .. automodule:: esibd.plugins.Notes :noindex: .. _`sec:text`: |text| Text ~~~~~~~~~~~ .. automodule:: esibd.plugins.Text :noindex: .. _`sec:tree`: |tree| Tree ~~~~~~~~~~~ .. automodule:: esibd.plugins.Tree :noindex: .. _`sec:ms`: |ms| MS ~~~~~~~ .. automodule:: esibd.displays.ms.ms.MS :noindex: .. _`sec:line`: |line| Line ~~~~~~~~~~~ .. automodule:: esibd.displays.line.line.LINE :noindex: .. _`sec:pdb`: |pdb| PDB ~~~~~~~~~ .. automodule:: esibd.displays.pdb.pdb.PDB :noindex: .. _`sec:holo`: |holo| Holo ~~~~~~~~~~~ .. automodule:: esibd.displays.holo.holo.HOLO :noindex: .. _`sec:live_displays`: Live displays ------------- .. automodule:: esibd.plugins.LiveDisplay :noindex: .. _`sec:deviceManager`: |deviceManager| Device manager ------------------------------ .. automodule:: esibd.plugins.DeviceManager :noindex: .. _`sec:console`: |console| Console ----------------- .. automodule:: esibd.plugins.Console :noindex: