.. |MLA (TM)| unicode:: MLA U+2122 .. |pm| unicode:: U+00B1 .. index:: Introduction, overview, GUI, panels .. _gui-overview-label: Graphical User Interface (GUI) ============================== With simple mouse clicks from the |MLA (TM)| GUI you can setup and control the instrument, record measurement data, plot data and save data. For many measurements working only with the GUI is sufficient. More complex measurements are programed with Python scripts and these can be run inside the GUI from the ``script panel``, as described in the section on :ref:`mla-programming-label`. The GUI consists of a set of **panels**, each with different functionality. All panels are opened from the ``Panels`` pull-down menu in the top menu bar. Closing a panel removes it from view, but it does not kill the instance of the panel in the software, and it may be re-opened in the same state that it was closed. Panels can be free-floating and re-sized, or docked in the main frame with different arrangements. Below we give an overview of the functionality and controls of each panel. .. index:: icon buttons, buttons, start measurement, pan-zoom, zoom, mouse actions, adjust subplots, saving plots .. _buttons-icons-label: common features +++++++++++++++ All plots have a toolbar and many toolbars have the following common icon buttons. |clear_icon| **Clear plot** : Press to clear the plot. .. |clear_icon| image:: ../icons/clear.png :width: 5mm |pan_zoom_icon| **Pan-Zoom**: when selected, a left-click-and-drag will cause the plot to zoom, starting from the point of click. Dragging horizontally will zoom only the x-axis, dragging vertically will zoom only the y-axis. Dragging at an angle controls the relative rate of zoom of each axis. A right-click-and-drag will grab the plot at the point of click and slide it in the direction of the drag. Performing these actions while holding down the **x**, **y** or **ctrl** keys will restrict the pan or zoom to occur only in the x-axis, y-axis, or preserving current aspect ratio, respectively. .. |pan_zoom_icon| image:: ../icons/move.png :width: 5mm |zoom_icon| **Zoom** : zooms to a selected rectangle with a right-click-and-drag over the plot. .. |zoom_icon| image:: ../icons/zoom_to_rect.png :width: 5mm |visible_icon| **Toggle visibility** : Use this tool to individually toggle the visibility of each line trace in the plot. .. |visible_icon| image:: ../icons/visible.png :width: 5mm |opentrace_icon| **Open saved line trace** : Open and plot saved line traces from text files saved with the Save data tool. .. |opentrace_icon| image:: ../icons/open.png :width: 5mm |savedata_icon| **Save data** : Save the data in the plot to a text file. .. |savedata_icon| image:: ../icons/save_data.png :width: 5mm |savefig_icon| **Save image** : The Save image button opens a dialog box for saving the figure to file. Several different formats (png, eps, pdf and more) are available. Sometimes you would like to save plots with a different aspect ratio, or change the relative size of the frame and text. Simply rescale the entire GUI or free-floating panel (click-and-drag on the lower right corner) before you save. This action will rescale the figure keeping plot limits, text and line size fixed. .. |savefig_icon| image:: ../icons/save_image.png :width: 5mm |play_icon| **Start measurement** : Press to start a measurement, depress to stop. .. |play_icon| image:: ../icons/play.png :width: 5mm **Mouse actions** on many plots allow for quick rescaling. * Hover over a plot and use the mouse wheel to zoom the y-axis from the pointers y location. * Hover over the x-axis just outside the plot and use the mouse wheel to zoom the x-axis from the pointers location. * Center-click either x-axis or y-axis just outside the plot frame to scale with the value in Axis settings. * Left-click either x-axis or y-axis just outside the plot to rescale that axis to include all data. * On some plots, a right-click anywhere inside the plot will open the ``Axis settings`` panel where you can enter the axis limits. .. index:: analog panel, range, configuring inputs, configuring outputs .. _analog-panel-label: analog panel ++++++++++++ The Analog panel controls the configuration of the MLA input and output ports. Here you can set the range, coupling (AC or DC) and the type of signal to be measured (differential or single-ended). The panel has one tab for each input and output port on the MLA-3. This panel has no function with the generation 2 MLA. **IN 1 to IN 4** There are two modes for setting up the inputs: ``Configuration`` mode has an interface very similar to a standard oscilloscope. Choose between: * ``DC`` or ``AC`` coupling. * ``single-ended`` or ``differential`` measurement (see :ref:`connections-label`). * ``50 ohm`` or ``1M ohm`` input impedance. * select an input ``Range``, from |pm| 40 mV to |pm| 10 V full scale. ``Manual switch control`` When activated, this mode allows for manual routing of the signal in the analog input stage. Use this mode if you require a special input configuration. Refer to the schematic diagrams in the section :ref:`analog-in-label`. The switches can be set from the :ref:`mla-api-label` with the function :func:`hardware.Hardware.set_input_relay`. When ``Configuration`` mode is activated, the state of each switch is displayed (checked = True). .. Caution:: When both switches dc=True and bypass=True, both + and - inputs will be pulled up to 1 V with respect to the grounded shield. **OUT 1 and OUT 2** * Select the output ``Range``, either |pm| 2 V to |pm| 12 V full scale. * Note that OUT 1 and OUT 2 ports are always differential. The MLA puts the output voltage between the + port and ground (SMA shield). A voltage of the opposite sign always appears between the - port and ground. If you use these ports differentially, the voltage difference between and + and - ports will be twice the set value. .. Caution:: The 12 V range is rather powerful and you can burn stuff with it. Be careful with what you are driving when using the 12 V range on these ports. .. index:: Aux Output panel, .. _aux-output-panel-label: aux output panel ++++++++++++++++ **OUT A - OUT D** Manually control the ``DC Bias`` for the **AUX OUTPUT** ports. For ``OUT A`` you can select the option ``Tone 0 amplitude`` to output a voltage proportional to the amplitude of tone 0. Change the ``Gain`` factor to change the the proportionality constant. You can also add and ``Offset`` to the output voltage. This feature is useful if you would like to do amplitude feedback, or example in AFM. Other types of feedback are possible, as documented in :class:`feedback.Feedback`. .. index:: lockin setup panel, read from MLA, write to MLA .. _lockin-setup-panel-label: lockin setup panel ++++++++++++++++++ The lockin setup panel can manually configure each tone in the |MLA (TM)|, or view the configuration made by a script. The information in all fields in this panel is not updated automatically, so the buttons at the bottom are important: ``Read from MLA`` will read the present configuration and display it in the panel. You can then edit any white-background field in the panel. ``Write to MLA`` sets the |MLA (TM)| to the present state of the panel. Press this after editing to effect the change. ``Tune...prio...`` click on this selector to choose which tuning function will be applied when ``Write to MLA`` is pressed. See :ref:`setup-and-tuning-label` for a description of the tuning functions. At the top of the panel: ``Measurement time window [ms]`` :math:`T_m` and ``Measurement bandwidth [Hz]`` :math:`\delta f` are not independent. :math:`\delta f = 1/T_m`. Changing one will force the other to change. ``Load`` and ``Save As`` buttons allow you to store configurations and reload them. There is one row for each tone in the |MLA (TM)|. The columns are: ``Freq. [kHz]`` shows the frequency of each tone. You can select ``n [-]`` to display (control) the frequency as an integer multiple of the ``Measurement bandwidth [Hz]``. ``Amp`` shows the amplitude of each tone. You can select to display (control) the amplitude in Volts ``[V]`` , or percent of full amplitude ``[%]``. ``Phase [o]`` displays (controls) the phase in degrees. ``Out 1`` and ``Out 2`` check boxes directs each tone to the output ports. When checked, the tone is applied to that port. ``IN Port`` displays (controls) at which input port the |MLA (TM)| will listen for each tone. You can choose between input ports ``1`` to ``4``, only one input port for each tone . ``Amp.`` and ``[o]`` display the measured amplitude and phase of each tone, when the **start measurement** button is depressed ( |play_icon| at the bottom). Press this button again to stop the continuous update of these fields. |monitor_icon| The **Monitor** button opens up a ``lockin monitor`` panel for each tone, which continuously displays the amplitude, phase and plots the quadrature amplitudes in the complex plane. Use the mouse wheel to zoom on the display. .. |monitor_icon| image:: ../icons/monitor.png :width: 5mm .. index:: oscilloscope, trigger modes, .. _oscilloscope-panel-label: oscilloscope panel ++++++++++++++++++ .. |1_icon| image:: ../icons/1.png :width: 5mm .. |2_icon| image:: ../icons/2.png :width: 5mm .. |3_icon| image:: ../icons/3.png :width: 5mm .. |4_icon| image:: ../icons/4.png :width: 5mm .. |imp_icon| image:: ../icons/imp_icon_24x24.png :width: 7mm .. |trig_icon| image:: ../icons/trig.png :width: 7mm .. |nsamples_icon| image:: ../icons/nsamples.png :width: 7mm The oscilloscope panel runs the |MLA (TM)| in a mode where all samples, or a down-sampled fraction of samples in one measurement time window, are transferred to the computer. The Fast Fourier Transform (FFT) of the data is taken in the computer and the amplitude is plotted vs. frequency, revealing the *entire* response spectrum. |play_icon| Start and Stop visual updates with the Start measurement button. |imp_icon| When the ImP icon is depressed, the |MLA (TM)| will alternate between between this window-transfer-mode and lockin data transfer. The lockin amplitudes will be displayed alternately with the entire spectrum. |1_icon| |2_icon| |3_icon| |4_icon| Selects the channels to display with the numbered buttons. |trig_icon| Opens a selector to control how the measurement is triggered. ``Free`` - Auto-triggers to get new data when plot is finished. ``Pixel`` - Auto-triggers at the start of the next lockin :ref:`measurement_time_window`. ``Pixel and TRIG IN 1`` - Triggers at the start of next measurement_time_window, when a trigger is received at Trigger Input 1. |nsamples_icon| Toggels open/close data fields above the tool bar to set: ``Number of samples:`` Number of samples in the time window displayed, and analyzed by FFT. ``Downsample factor:`` will average the given number of samples before transfer to the computer. Down-sampling reduces the amount of data handled, resulting in faster Fourier analysis and plotting, but it also reduces the time resolution and the maximum frequency in the Fourier transform. ``Use value from Lockin`` when checked, sets the number of samples to that used by the lockin. .. index:: lockin history, record measurement, add/remove subplots, axis settings .. _lockin-history-panel-label: lockin history panel ++++++++++++++++++++ The Lockin history shows the most recent lockin data plotted as a function of time. .. |record_icon| image:: ../icons/record.png :width: 5mm |record_icon| **Record measurement** : When depressed will save lockin to a file with the path `IMP Sessions and Settings/data/session_folder/rec0123.txt``, where the session_folder is named with the date of measurement, and the record file number is automatically incremented. Depressing Start or Record, will stop saving and close the file. All lockin channels are saved to file. The history can be displayed in a multitude of ways: .. |nsupblots_icon| image:: ../icons/nsubplots.png :width: 5mm |nsupblots_icon| **Set number of subplots**: controls the matrix of subplots in the figure. Right-click on each subplot to open up the ``Axis settings`` dialog box for that subplot. ``Select frequencies ->`` opens a dialog with check boxes to select the frequency (with its associated input port) to be plotted in this subplot. ``Quantity:`` selects which lockin data to plot: Amplitude, phase, I-quadrature, or Q-quadrature. ``Scale type:`` selects the scale of the vertical axis: ``Linear``, ``Logarithmic`` or ``Modulo`` where the latter will wrap between ``Y min`` and ``Y max`` . ``Legend:`` controls the placement of the legend in the subplot axis. ``Y min``, ``Y max``, ``history length [s]`` control the subplot limits. These limits are applied hitting enter on the keyboard, or clicking on the plot. .. index:: script panel, startup script, built_in_scripts, default.py .. _script-panel-label: script panel ++++++++++++ The |MLA (TM)| GUI has a built-in script editor with the standard functionality, including the ability to execute the script with the ``Run`` button. It is often not practical to have buttons and knobs to individually control each tone. Furthermore, setting up a multifreqeuncy measurement requires some thought and calculations are needed to make sure that all tones fit in to the same 'key' (see :ref:`setup-and-tuning-label`). Configuring the measurement is best done with a script. The ``Startup`` button indicates the script to be opened and executed when the software is started. Press this button to change the startup script to the currently open script. The system is delivered with a ``default.py`` startup script stored in ``IMP Sessions and Settings/settings/mla_scripts/built-in``. This script can be modified and saved with a new name in the ``IMP Sessions and Settings/settings/mla_scripts`` folder. At every start of the |MLA (TM)| software, all scripts in the ``built_in`` sub-folder will be overwritten and restored to their originally delivered version. A more complete discussion of **Python** scripts and detailed documentation of all functions that control the that control the |MLA (TM)| is given in the chapter on :ref:`mla-programming-label`, complete with :ref:`example-scripts-label`. .. index:: user plot .. _user-plot-panel-label: script plot panel +++++++++++++++++ The script plot panel is a panel with an empty figure that the user can program to plot data in a script. See :ref:`mla-programming-label` for a discussion of how to write and run scripts. There you will find an example script for :ref:`plotting-in-gui-label` .. index:: frequency sweep, de-embedding, use correction, use multifrequency .. _frequency-sweep-panel-label: frequency sweep panel +++++++++++++++++++++ One often measures response at very many frequencies spread evenly over some band, for example when searching for a very sharp resonance. The frequency sweep panel is designed for this purpose. The sweep is actually not continuous, but a sequential stepping between closely spaced, discrete frequencies. This type of measurement is speed up significantly when using the multifrequency capability of the |MLA (TM)|. The ``Run sweep`` button starts the measurement, changing to ``Stop`` when activated. Edit the ``Start frequency [kHz]`` and ``Stop frequency [kHz]`` fields to change the sweep range. ``Bandwidth`` sets the :ref:`measurement_bandwidth`, or the inverse of the :ref:`measurement_time_window`, which is time needed to measure the response. ``Number of points`` sets the total number of points in the sweep range. Note that the frequency spacing between points will not be exactly equidistant, but as close as possible while maintaining the constraints on bandwidth and drive frequencies discussed in the section on :ref:`leakage-label`. ``Drive amplitude [V]`` controls the peak amplitude at the output port. ``Use multifrequency`` when activated, will use all available lockins to collect many points in parallel. This speeds up the measurement considerably, while keeping the bandwidth and therefore SNR at the same level. With multifrequency a sweep will only give the same result as a single-frequency sweep if the system is linear. A nonlinear system will induce intermodulation between tones in the multifrequency drive. ``Locate Peak`` when selected will automatically zoom on the maximum value in the sweep and perform a more detailed sweep. This feature is very useful for resonance finding. When it is activated, the ``Resonance frequency`` and ``Quality Factor`` are determined by fitting to a Lorentzian line-shape and displayed at the bottom. ``Use Correction`` allows one to 'de-embed' linear response from other spurious response in measurement chain between input and output of the |MLA (TM)|. Sometimes electronic equipment between the |MLA (TM)| ports and the device-under-test (DUT) can cause frequency-dependent amplitude and phase shifts to the signal. Use Correction compensates for any linear transfer of the signal due to these components 'embedded' in the measurement chain. The compensation is made using a procedure called de-embedding, performed in two steps: 1. A frequency sweep is performed while by-passing the DUT (insert a short in place of the DUT). After this sweep, press the ``Set Correction`` button, which transfers the result of this sweep to an internal correction file. 2. Put the DUT back in to the measurement chain and check the ``Use Correction`` check-box. All subsequent sweeps performed with this box checked will correct for the amplitude and phase shifts measured in the first step. **Note:** you must do this procedure again if you change anything in the measurement chain, or change any settings that configure the sweep. In summary: * ``Use Correction`` will correct the measurement for an arbitrary *linear*, frequency-dependant transfer function embedded between the output and the input points of the measurement chain. * ``Set Correction`` stores the last-measured sweep to an internal file and uses this file for the correction. ``Clear Plot`` removes all previous sweeps and the fit. .. index:: frequency counter .. _frequency-counter-panel-label: frequency counter panel +++++++++++++++++++++++ To use the frequency counter panel you must first load and run the script ``frequency_count.py`` located in the ``IMP Sessions and Settings/settings/mla_scripts/built-in`` folder. When |play_icon| is depressed, the plot updates a time record of the frequency of the signal at the input port. Edit the script to change the input port and plotting: ``samples_per_measurement`` defines the time window used to determine the frequency. Must be a power of 2. ``downsample_factor`` is the number of raw ADC samples averaged, to create one measurement sample. ``frequency_correction_factor`` software calibration constant. ``port`` controls the |MLA (TM)| for the frequency counter function. .. index:: message log .. _message-log-label: message log panel +++++++++++++++++ The message log panel contains a record of output from the software. It is very useful debugging problems with scripts. Print statements in a script will be output here. .. index:: Python shell .. _python-shell-panel-label: Python shell panel ++++++++++++++++++ The Python shell panel allow you to execute Python statements in real time. All functions controlling the :ref:`mla-gui-label` and the :ref:`mla-api-label` are available in this shell. The shell shares its namespace with scripts executed in the script panel, so that any variable or function created in a script can be accessed from the shell and vica-versa.