Graphical Interface

This part discusses the use of the Graphical User Interface (GUI). For tutorial on using tesliper in Python scripts, see tutorial.

On Windows system you may start the GUI by downloading and double-clicking Tesliper.exe file available in the latest release, as described in the Installation section. Executable files are not available for other systems, unfortunately, but you may start the GUI from the command line as well:

$ python -m pip install tesliper[gui]  # only once
$ tesliper-gui  # starts GUI

Note

If you’d like to start the graphical interface from the local copy, you may also run it as a module with python -m tesliper.gui.

Please note that the first launch may take additional time. After the application starts, a window like the one bellow will appear. It’s actual looks will depend on your operating system.

The Interface is divided in two parts: controls on the left and views (initially empty) on the right. Controls panel are further divided into sections, some of which may be collapsed by clicking on the section title (those with a small arrow on the left). Each section will be described further in this tutorial, in the appropriate section.

There are tree views available: Extracted data and Energies list summarize all conformers read from files. Extracted data details what data is available and shows status of calculations for each conformer. Energies list shows values of conformers’ energies calculated by quantum chemical software and derived values: Boltzmann factors and conformers’ populations.

Reading files

tesliper supports reading data from computations performed using Gaussian software. To load data, use controls in the Extract data section. Choose files button allows you to select individual files to read using the popup dialog. Choose folder button shows a similar dialog, but allowing you to select a single directory - all Gaussian output files in this directory (but not subdirectories) will be read. Finally, using the Recursive button will also read files form all subdirectories, recursively.

Note

Make sure you do not have mixed .log and .out files in the directory, when using Choose folder button.

Once you select files or directory and confirm your selection, the process of data extraction will start and Extract data view will be updated for each read conformer. It will show if calculation job terminated normally (Termination), if conformer’s structure was optimized and if optimization was successful (Opt), if extended set of energies is available (Energy), what spectral data it available (IR, VCD, UV, ECD, Raman, ROA), how many imaginary frequencies are reported for conformer (Imag), and what is conformer’s stoichiometry (Stoichiometry).

When data extraction is finished, the status barr att the bottom will show Idle again. After reading first portion of files, you may tick the Ignore unknown conformers option. When this option is ticked, tesliper will only read files that correspond to conformers it already knows (judging by the filename).

Trimming conformers

Conformers may be marked as kept not kept (trimmed). Only kept conformers are processed by tesliper, trimmed ones are ignored. This mechanism allows you to select which conformers should be included in the final averaged spectrum, etc. Trimmed conformers are shown in gray.

Kept conformers section shows how many conformers contain certain data and allows to easily keep/trim whole groups of conformers, using keep and trim buttons beside the appropriate group. You may also keep/trim individual conformers by ticking/unticking checkboxes beside the conformers name (left of Filenames column).

After finished data extraction and after each manual trimming, auto-trimming is performed to make sure corrupted or invalid conformers are not accidentally kept. Checkboxes in the Auto-trim subsection, shown below, control which conformers should be always trimmed.

Tip

Incomplete entries are conformers that miss some data, which other conformers include, e.g. those that were left out in one of calculations steps. Inconsistent data sizes indicates that some multi-value data has different number of data points than in case of other conformers. This usually suggests that conformer in question is not actually a conformer but a different molecule.

Trimming with sieves

The Energies and structure section, described in this part, is related with the Energies list view. This view shows, as the name suggests, list of energies for each conformer and energies-derived values.

Using a Show: drop-down menu you may select a different energies-derived data to show in the view. Delta is conformer’s energy difference to the most stable (lowest-energy) conformer (in \(\mathrm{kcal}/\mathrm{mol}\) units), Min. Boltzmann factor is conformer’s Boltzmann factor in respect to the most stable conformer (unitless) and Popuation is population of conformers according to the Boltzmann distribution (in perecnt). Original Energy values are shown in Hartree units.

Both types of sieves provided depend on the selected value of the Use: drop-down menu. It determines, which energy values are used by the sieves. Only available energies wil be shown in the list. In case their names are not intuitive enough, here is the explanation:

Thermal: sum of electronic and thermal Energies;

Enthalpy: sum of electronic and thermal Enthalpies;

Gibbs: sum of electronic and thermal Free Energies;

SCF: energy calculated with the self-consistent field method;

Zero-Point: sum of electronic and zero-point Energies.

The Range sieve lets you to trim conformers that have a current Show: value outside of the specified range. After you fill the Minimum and Maximum fields to match your needs, click Trim to... button to perform trimming. The example below shows trimming of conformers, which Free Energy-derived population is below 1%. Please note that valuesin the Energies list are recalculated and Minimum and Maximum fields are updated to show real current max and min values.

The RMSD Sieve lets you mathematically compare structures of conformers and trim duplicates and almost-duplicates. RMSD stands for root-mean-square deviation of atomic positions and is a conformers similarity measure. The sieve calculates the average distance between atoms of two conformers and trims the less stable (higher-energy) conformer of the two, if the resulting RMSD value is smaller than value ot the Threshold field.

Calculating an RMSD value is quite resource-costly. To assure efficient trimming, each conformer is compared only with conformers inside its energy window, defied by the Window size filed value. Conformers of energy this much higher or lower are automatically considered different.

Temperature of the system

The Energies and structure section also allows you to specify the temperature of the studied system. This parameter is important for calculation of the Boltzmann distribution of conformers, which is used to estimate conformers’ population and average conformers’ spectra. The default value is the room temperature, expressed as \(298.15\ \mathrm{Kelvin}\) (\(25.0^{\circ}\mathrm{C}\)). Changing this value will trigger automatic recalculation of Min. Boltzmann factor and Population values, and average spectra will be redrawn.

New in version 0.9.1: The Temperature entry allowing to change the temperature value.

Spectra simulation

Calculate Spectra controls section and Spectra view tab allow to preview the simulation of selected spectrum type with given parameters.

The Spectra view tab is initially empty, but when you select one of the available Spectra types, Settings subsection will become enabled and the spectrum will be drawn.

Tip

You can turn off automatic recalculation of the spectrum by unchecking the Live preview box.

Beginning and end of the simulated spectral range may be set using Start and Stop fields. The view on the right will match these boundaries. Please note that Start must have lower value than Stop. There is also a Step field that allows you to adjust points density in the simulated spectrum.

Width field defines a peak width in the simulated spectrum. It exact meaning depends on the chosen fitting function (see below). For gaussian fitting Width is interpreted as half width of the peak at \(\frac{1}{e}\) of its maximum value (HW1OeM). For lorentzian function it is interpreted as half width at half maximum height of the peak (HWHM).

Tip

You may change fields’ values with the mouse wheel. Point the field with mouse cursor and allow for a small delay before switching form the scroll mode to the value-changing mode. Move the mouse cursor away from the field to switch back.

Finally, you may choose the fitting function used to simulate the spectrum from the calculated intensities values - this will have a big impact on simulated peaks’ shape. Two such functions are available: gaussian and lorentzian functions. Usually lorentzian function is used to simulate vibrational spectra and gaussian function for electronic spectra.

The default spectra preview is a Single file preview that allows you to see the simulated spectrum for the selected conformer. You may change the conformer to preview using the drop-down menu shown in the screenshot below.

When in a Single file preview, spectral activities used to simulate the spectrum are also shown on the right. You may turn this off by unticking the Show activities box.

You can also preview an population-weighted average spectrum of all kept conformers, by selecting Average by energy. The drop-down menu lets you select the energies that tesliper should use to calculate conformers populations.

The final option is to show all kept conformers at once by selecting Stack by overview option. The drop-down menu allows to choose a color scheme for the stacked spectra lines.

Comparing with experiment

It’s possible to and an overlay with the experimental spectrum to Single file and Average by energy previews. To load an experimental spectrum, use Load from file button in the Experimental spectrum subsection. tesliper can read spectrum in the .txt (or .xy) file format. Binary .spc formats are not supported.

When you choose the experimental spectrum file, it’s curve is drown on the right with respect to the Start and Stop bounds. Red color is used for the experiment. In case of a significant difference in the magnitude of intensity in both spectra, the second scale will be added to the drawing.

The scale of the simulated values may be automatically adjusted to roughly match the experiment with the Auto-scale button. It may be also adjusted manually by changing the value of the Scaling field.

Similarly, Auto-shift button and Offset field let you to adjust simulated spectrum’s position on the x-axis. Positive Offset shifts the spectrum bathochromically, a negative one shifts it hypsochromically.

Scaling and Offset values are remembered for the current spectra type, just like the other parameters.

Data export

Calculated and extracted data may be exported to disk in three different formats: text files with Export to .txt button, csv files with Export to .csv button and Excel files with Export to .xlsx button. Clicking on any of those will bring up the Export... dialog.

At the top of the Export... dialog is displayed the path to the currently selected output directory. It may be changed by clicking on the Browse button and selecting a new destination. Files generated by tesliper will be written to this directory.

On the left side of the dialog window you may select what type of data you want to export by ticking appropriate boxes. Once you hover over the certain category, more detailed list of available data will be shown on the right. By ticking/unticking selected boxes you can fine-tune what should be written to disk.

In the Spectra category, beside each available spectra type, there is a note that informs if calculation parameters were altered by the user. Spectra will be recalculated with current parameters upon the export confirmation.

Creating Gaussian input

Clicking on the Create .gjf files... will open a dialog window that lets you setup a next step of calculations to conduct with the Gaussian software.

Similarly to the previews one, this dialog also features a Path field that specifies the output directory, which may be changed by clicking on the Browse button. Bellow it is the Geometry type drop-down menu that allows you to select, which geometry specification should be used in the new input files. Input is the geometry used as an input in the extracted .log/.out files, Last read is the one that was lastly encountered in these files. Optimized is the geometry marked as optimized by Gaussian, but it is only available from the successful optimization calculations. You also need to specify the Charge and the Multiplicity of the molecule.

Below are the Route and Comment fields. The first one specifies the calculation directives for the Gaussian software. The second one is a title section required by GAussian.

Further below is the expandable Link0 commands panel that allows to specify Link 0 directives, which define location of scratch files, memory usage, etc. Select a command name from the drop-down menu, filed on right will show a hint about its purpose.

Provide a value in the input filed and click a + button to add a command. It will be added to the list below. You can update the selected command by providing a new value and clicking the + button again or remove it by clicking the - button.

Path-like commands may be parametrized: ${conf} will be substituted with the name of conformer and ${num} will be substituted with the sequential number.

Finally, you can add a post-geometry specification. It will be written to the end of each .gjf file.

Saving session

You can save a session (all data, along with current trimmed and parameters) with a Save session button. A popup dialog will be opened, where you can specify a target session file location.

To load previously saved session use the Load session button. You can also discard all currently held data by clicking the Clear session button.

Warning

Loading and clearing session cannot be undone! A confirmation dialog will be displayed for those actions.