Quantics Analysis GUI — User documentation

The Quantics Analysis GUI is an alternative for using the existing quantics analysis commands on a command line interface. It serves as an easier and more user-friendly way to perform analysis on the output of a quantics simulation.

Getting started

The GUI requires python ≥ 3.10 and the packages PyQt5 and pyqtgraph to function (installing pyqtgraph should also install numpy, which is also required). If you do not yet have python installed, it is recommended to use conda. A conda environment with the prerequisites is available by navigating to %QUANTICS_DIR%/source/analyse/analysis_gui/ and executing

conda env create -f environment.yml

If the environment is already created, you can use

conda activate quantics_gui

Open the GUI by using

python3 $QUANTICS_DIR/source/analyse/quantics_analysis_gui.py

If you do not wish to use conda, you can install the required packages directly using pip:

python3 -m pip install PyQt5 pyqtgraph

Opening a directory

After successfully using the quantics command, a folder should have been generated with output files. To navigate to the folder in the GUI, you can click FileOpen Directory, type Ctrl + O, or the click on the button in the top-right corner. Alternatively, you can paste the directory directly into the ‘Current directory’ line.

Performing an analysis

On the left side of the screen, various analyses have been split into different sections. To perform an analysis, click on one of the tabs (namely Analyse Convergence, Analyse System, etc.) and click on the radio button with the analysis you want. Some options have an additional options box that control the inputs to the fuction (e.g. specifying the state to look at). When you are ready, click Continue.

The output is on the right side of the screen. Depending on the analysis chosen, the output is written to the plot widget or the text widget. Most analyses change the plot widget, in which case the text widget shows the standard output (stdout) of the command if you had used it on the command line, or the .log file generated from the command. You can switch between the two at the bottom of the screen.

Once you have finished with analysis, you may wish to delete extra files generated by the GUI (see Cleanup Directory).

Coordinate selection

In order to plot multi-dimensional data, a ‘cut’ of the data may have to be performed. This is done using the coordinate selection option in the extra options box. You can choose the degree of freedoms that are x and y, then choose fixed values for the other DOFs. If both x and y are selected, a contour plot is produced. If only x, a normal line graph.

Specific information on an analysis

You can hover over one of the analysis radio buttons to get an overview of what it does. If the message is in the form ‘Executes [command]’, the GUI will internally call the quantics command. You can then look up information for that command in the original analysis documentation.

The plot widget

You can move the data in the plot by holding left-click and dragging around. To zoom in, right-click and drag horizontally to zoom the x-axis, vertically to zoom the y-axis, or diagonally for a combination. You may also use the middle mouse button for this purpose.

Alternatively, right-click and click Mouse mode1 button, which replaces the left-click with a zoom option; simply drag a box around the part of the graph you want to zoom into. To return to automatic sizing, right click and click View all or click the A in the bottom left of the widget.

If you have the legend open (which it is by default), you can click on the lines in the legend to hide plotting for that line. This is useful if the plotted data overlaps heavily and you want to look at one line in particular, for example.

Animated plots

Some analysis options allow you to control time using the ‘scrubber’ at the bottom of the screen. You can also click the play button to automatically increase time in the plot. Control how fast this goes using the Speed button. This button also changes the framerate if you save the video as well.

For animated 1D plots, the y-axis rescales automatically over time. To prevent this, right-click, go to Y axis and click Manual to fix the y-axis limits to their current values.

Context menus

Context menus are shown when right-clicking on the text widget or the plot widget.

Customising the plot widget

It is possible to change the some properties of the plot by right-clicking → Plot Options. In this sub-menu, you can change the title of the plot (Custom title), whether to show the legend (Show legend) as well as enabling the grid/changing its opacity (Grid).

The GUI is not intended to produce publication quality graphics. If more customisation is needed, it is recommended to save the .npy data (see section below) then use a package such as matplotlib to read the data and produce your own graphics.

Saving files, images, and videos

You can save the text output in the text widget by right-clicking → Save text, or the raw numpy data in a plot with Save .npy data. A menu should pop up asking you the name and location of the file you want to save.

In order to save an image of the current plot, right-click and choose Export... in the plot widget’s context menu. Then you can choose whether to save as an image (png, jpg) or a vector graphic (svg) of the current window. In order to save a video, you must have ffmpeg installed, which can be obtained from your package manager, e.g. for apt,

sudo apt install ffmpeg

after which you can save similarly to the other options.

To make images/videos larger or smaller, simply resize the window accordingly.

Line wrap

In the text widget, if there are too many characters on one line, a horizontal scroll bar will show up to see the rest of the line. If you do not want this, you can enable this option to split any long lines over multiple lines.

Transformations

A number of transformations can be applied to the current plot by right-clicking → Plot OptionsTransforms. Some convenient ones include log X, log Y, and dy/dx.

Options menu

The options menu is on the menu bar on the top of the GUI.

Timeout

When performing an analysis, the GUI calls the quantics analysis programs internally. The timeout option sets how long to GUI waits for the analysis program to finish before giving up. Note, this option only applies to the quantics analysis program and not any analysis the GUI does itself.

Cleanup directory

Some calls to quantics analysis programs leave data files for the GUI to read. These files are analysis output files (not to be confused with the output files from quantics), and are read by the GUI for plotting purposes. After an analysis is finished, these files are not removed automatically. If you wish to remove them, click OptionsCleanup directory. The GUI finds any analysis output files in the current directory and deletes them (after asking for your permission, of course).

Allow additional flags

For certain analyses, an options box may show up with more controls. In general, these toggle the flags and inputs to the corresponding quantics analysis program. However, not all options may be covered, and for technical users, you can manually input additional flags by using OptionsAllow additional flags. An additional box will show at the bottom of the analysis toolbar for you to enter these extra options.

An example where this may be useful is if you want to use the restart file rather than the psi file. Select the relevant command, then type -r into the additional flags box, before continuing as normal.

No command mode

This option is convenient if you already have the quantics analysis output already, and want to show it in the GUI without calling the quantics analysis program again. If this option is on, the GUI will try to read the relevant file without calling the corresponding quantics program.

This may be useful if the analysis program takes a long time to compute. You can call the original command on the CLI, then wait in the background for it to finish, or SSH into a HPC cluster and call it there. Once it has completed, navigate to the directory of the output file and select the relevant command in the GUI, then continue as normal in no command mode. The GUI should plot the output normally.

For certain analyses, the extra options must be set correctly, e.g. for the 1D density, the degree of freedom and state selected must match with the filename.