.. 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<data_path>`, :ref:`config path<config_path>` and if applicable :ref:`plugin path<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<sec:live_displays>`. 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<sec:genetic_algorithm>`.

Display
   If selected, channel will be shown in the corresponding :ref:`live display<sec:live_displays>`.

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<sec:live_displays>`.

Line style
   The line style is used to further distinguish channels with similar color in
   the :ref:`live display<sec:live_displays>`.

Group
   :ref:`Live displays<sec: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<sec:live_displays>`.

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<sec:displays>` and :ref:`live display<sec:live_displays>`.

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<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<sec: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:
