UNEX User Manual

UNEX has built-in constants and data from different external sources. Fundamental physical constants are used from the CODATA2022 collection [6]. The relative atomic masses of isotopes have been taken from the AME-2020 work of Wang et al. [7]. Scattering factors for the diffraction of electrons were taken from the 2004 (third) edition of the International Tables for Crystallography Volume C [8].

UNEX is distributed for free. Conditions of its distribution are of "AS IS" type. You use this program on your own risk. Before downloading and using UNEX you must accept the license agreement, see files license.html, license.pdf or license.txt.

If you think you’ve found a bug or some incorrectness in UNEX the first thing to do is to check everything including your commands, control keywords and data. Second, make sure you are using the latest version of UNEX. If you still cannot find the source of the problem it is possible to write an e-mail to the main UNEX developer (see below). Before you do so, it is highly recommended to isolate the problem and to send a smallest possible input file generating erroneous or suspicious results.

For questions, comments or bug reports you can use one the following E-mail addresses of the main UNEX developer, Dr. Yury V. Vishnevskiy

Reading this manual you can meet numbers expressed using scientific notation and symbol e, for example 5.5e13. This corresponds to base-10 exponentiation, so the number above is equivalent to 5.5×10¹³. Note, UNEX can read numbers in scientific notation.

In many examples you can see triple dots …​. This does not reflect the input format but just indicates that further data may follow. Otherwise the examples would be too long.

UNEX program is distributed together with some supplementary programs, testing files, documentation and other parts. For the installation there is no need to do any special actions, simply copy all files from the distribution to any suitable directory. It is recommended to place them to one dedicated directory listed in the environment variable PATH so that the executable can be called from any directory in the system. If all UNEX files are in one place then it is also easier to update them by replacing old files in this particular directory. Checking for new versions and updating can be also performed automatically by starting the special script update.sh (in Linux and other UNIX-type operating systems) or update.cmd (for Windows). Note, automatic update may not work for different reasons. First, it requires access to internet for checking the availability of new versions. Second, the scripts use some system utilities, which must be already installed. Finally, the automatic update may possibly not work due to some major changes in the procedure. In this case you need to download the newest version of UNEX and install it manually.

UNEX is a command line program. In order to use it, an input file should be prepared first (for details see below). Starting UNEX without any input file prints general information about its usage. In the simplest case real usage UNEX requires only one command line parameter, the name of the input file. After starting UNEX the input file remains unmodified and an output file is created, which contains all results in text form. If you do not indicate the output file name explicitly in the command line, then UNEX automatically creates one named similar to the input file with added underline symbol together with a number and an extension .log. The number indicates version of the output and it increases each time when run UNEX with the same input file. Thus, in this mode output files are never overwritten. Alternatively, you can define in command line the name for the output file explicitly.

Input data and commands for UNEX are provided in normal text files (not to mix up with files produced by text processors like OpenOffice). Data fields are used for introducing input information. For their arrangement the so-called tags are used, i.e. a logically complete fragment of data is placed between two certain words which are called tags. In general they may contain any letters. A standard practice is to use constructions like

Here <myinfo> and </myinfo> are examples of opening and closing tags, respectively. In spite of considerable number of different commands and field types, all these elements follow similar pattern, which is easy to understand and use. The sequence of commands is naturally important. It is not recommended to use very long strings in input files.

The lexical structure of UNEX input follows the principles:

The syntax for setting keywords is simple, like

The values can be strings, integers or floating point numbers. Usually keywords accept only one value. Some other keywords can accept list of strings separated by the semicolon ; symbol, for example

The syntax for commands is usually complex, with indication of possible mode, processed objects, sources of input data and control parameters in form of keywords.

For example

Here the first word BASE is the name of the command. After the colon symbol : goes the mode which can also be understood as a subcommand. Here for BASE the mode READ is used, which indicates that UNEX must read some basic information. The other two arguments are tags pointing to the start and the end lines of the respective field containing the basic information. Thus, UNEX will try to find the field and read the corresponding information from the input file between the following tags

Note, whitespaces are allowed so, for example, the following syntax is also possible:

Some other commands must contain an identifier of the object to be processed or for which some information must be read, for example

will read a Z-matrix for the molecule already defined as mol.

Any line in the input file can be commented out. For this in the very first position of the line you should type the symbol #. It is also possible to place a comment after command or keyword, for example

In most cases UNEX input files begin with introduction of some basic and global information. For this purpose the BASE command is used:

The BASE field can contain various global control keywords. Depending on the job type different keywords can be important. The keyword Molecules is used most often whenever models of molecules are created and manipulated, for example in structural analyses. See section Molecules on how to read in molecule-specific keywords.

Sometimes it is useful to apply different settings on different stages of the job. This can be achieved by calling the BASE command several times, for example

Below is the list of keywords valid in the BASE field:

There are special keywords with prefixes HashAbsEps and HashRelEps, indicating absolute and relative (in fractions of unit) precision for various types of data used in calculating of hashes. They are required only for testing purposes and thus not documented here.

For each molecule declared in BASE a special field must be defined, which contains some general information about the molecule. The starting and ending tags of this field must be constructed as <name_of_molecule> and </name_of_molecule>, respectively. For example, for a molecule mymol the corresponding field is

Possible keywords in field of molecule:

Images are defined in UNEX similar to molecules — i.e. image names are listed using the Images keyword in BASE. Accordingly, for each image can be defined a field with starting and ending tags constructed from the name of this image. For example

Valid keywords in image fields are:

In general case data samples are defined in UNEX similar to molecules. You need to use the keyword DataSamples and provide respective field(s). The code below demonstrates an example:

Keywords available for data samples are:

A data sample can also be imported directly from file. For this the DATASAMPLE command must be used with the mode IMPORT:

Note, with the optional keyword ImpDS you can explicitly define the name (identifier) for the imported data sample, otherwise a new one will be created automatically.

In order to construct a dynamic model for molecular part of electron diffraction intensity a potential function must be introduced. This can be done using the MOLPEFUNC command:

here mol is the name of molecule, otag and ctag are opening and closing tags of the data field as usually, the keyword Form accepts options numeric and parametric and the optional keyword Format can accept only unex.

With Form=numeric the potential energy function in numeric form can be introduced, for example:

Here in the first column are the values of the geometric parameter corresponding to the dynamic coordinate In the second column are the respective energy values. Their units can be defined by MolPEFuncEUnits keyword in BASE. After reading the data UNEX performs two major actions. First, all the values are shifted so the the minimal value equals to zero. Second, the data are approximated with a function. Type of the function depends on the PEFuncType setting in the field of the respective molecule. If it is a parametric function then the PEFuncCoefNum keyword should be set to a proper value. Note, this keyword defines total number of parameters in the potential function including free term, if applicable. For example, the combination PEFuncType=cos1 and PEFuncCoefNum=3 defines the following potential energy function (note the numeration of parameters V_i):

Similarly, for PEFuncType=polynom and PEFuncCoefNum=5 the potential function will be

The model gauss for potential function has no free term and the combination PEFuncType=gauss and PEFuncCoefNum=6 gives

The data field in this format may contain two special keywords: PrmValInit and PrmRefGrp. The first one is for setting initial values for parameters of the model potential function. They are used in approximation procedure. Generally, for cosine series they are not required but for a sum of Gaussians it is very advisable to set them to some reasonable values, which will be refined further by UNEX upon introducing the numeric form of the function. The other keyword, PrmRefGrp, is for setting group numbers for those parameters, which should be refined in LSQFUNC:MINIMIZE and related commands. The example below demonstrates both keywords

Several important points can be mentioned for this example.

The other option, Form=parametric, is for the case of introducing particular values of parameters for the potential energy function. The following example demonstrates the usage of this format.

In this data field at least two columns must be provided. The first column is for parameter indices, the second column contains values of respective parameters. The optional third column can contain refinement group numbers for the parameters. In this example the introduction of values for the first five parameters is done. As in the examples above the keys PEFuncType and PEFuncCoefNum here must also be defined before reading the data. Additionally, group numbers 101, 102 and 103 are assigned to parameters 1, 2 and 4, respectively. Note, the numbering of parameters starts from zero. The scheme for the numbering is described above. In particular, for the gauss model the special scheme is used: the parameters 0, 1 and 2 correspond to V, Δ, and w of the first Gaussian in the sum. The next tripple, 3, 4 and 5, corresponds to the parameters V₂, Δ₂ and w₂ (parameters of the second Gaussian) and so on.

It is possible to execute several MOLPEFUNC:READ commands for introducing different values of parameters and/or group numbers if required. Also it is not necessary to set all parameters in the data field. It is possible to define values only for selected parameters. In this case the other parameters will not be affected.

A term in ED is a pair of atoms with associated parameters like distance, vibrational amplitude, correction and asymmetry (anharmonic, phase-shift) constant. They are required for calculation of molecular intensities. All these parameters can be introduced with the EDTERMS command:

where the optional Format keyword can accept values unex (this is default), shrink or eldiff, which correspond to UNEX, Shrink and ElDiff programs, respectively.

Below is an example of data field in the most complete UNEX format:

Here each line includes a pair of atoms, the r_a distance between these atoms, vibrational amplitude l, vibrational correction corr, asymmetry constant a, group number gl for the amplitude and group number gr for the distance. The format is flexible, allowing omitting some parameters as shown below. Distances, amplitudes and corrections must be given in Å. By default the type and units for asymmetry constants depend on the current setting of the EDImolAnhTrmModel keyword (for details see see chapter Models for ED intensity). For EDImolAnhTrmModel=asym the default expected type is here asymmetry parameter κ and the expected units are ų. In case of EDImolAnhTrmModel=morse the expected type is Morse parameter and the units are Å^-1. However, it is possible to define explicitly the type and units for the input a-parameters with the local keyword AsymUnits as in the example:

The setting kA3 indicates here that the input a-values are in fact asymmetry constants κ in ų. If the global keyword EDImolAnhTrmModel is set to morse, then these values are converted internally to Morse constants according to the formula

where l is the respective amplitude taken from the same current input. Another option is kpm3 if κ are given in pm³. Yet another option is AsymUnits=c3pm3, indicating that the input values are c₃ parameters from the cumulant approximation [19]. They are converted internally to asymmetry parameters as κ = 10^-6c₃/6. Again, if EDImolAnhTrmModel=morse, than Morse constants are calculated automatically as described above. Also it is possible to indicate explicitly the input of Morse constants in Å^-1 by defining AsymUnits=moAm1. If at this point the current setting is EDImolAnhTrmModel=asym, then the input Morse constants are automatically recalculated into asymmetry parameters κ according to the formula above.

If you do not need to assign group numbers (when it is not intended to refine amplitudes and/or distances), there is no need to set them to zeros explicitly. Instead, they may be simply omitted

However, for the refinement of only r_a distances, group numbers for both amplitudes and distances must be provided explicitly, for example:

If a-parameters are zero, they can also be omitted. Note, the group numbers may still be defined, for example:

If the vibrational correction is zero and the respective a-parameter is also zero, then both numbers may be omitted. However, if the correction is zero but the a-parameter is not zero, then both numbers must be defined explicitly:

Another format option is shrink. It is implemented for reading data produced by the Shrink [20] program. Specifically UNEX expects data as it is printed by Shrink in tables for the second approximation:

From the given data UNEX reads amplitudes (from the fifth column) and corrections (Shrink prints them in the column K, in the second approximation they correspond to r_h1-r_a). The values in columns <dr(loc)> and <dr(har)> are ignored. Note, in Shrink output the integers in the last column are simply indices of the corresponding atom pairs. In contrast, UNEX interprets them as group numbers. In reality it is very unlikely that one would leave them as they are. Normally you need to delete this column and assign group numbers manually, if required. Also, two integer numbers can be provided if groups for both amplitudes and distances need to be defined.

If you want to use anharmonic corrections from Shrink, the column K must be substituted with the column r_e-r_a from the very last table produced by Shrink, so the format remains for UNEX unchanged. In the example below corrections to equilibrium structure are used and the integers are removed.

The third available format eldiff is for introducing data produced by the ElDiff [21] program. Here is a shortened example of such data field:

Vibrational corrections are calculated from the input data as differences Re-Ra. Amplitudes and asymmetry parameters c3/6 are read as they are given. Note, the input c3/6 values in pm³ are converted internally to asymmetry parameters κ in ų. However, they can be internally further converted to Morse parameters if the EDImolAnhTrmModel keyword is set to morse. As usually, optional integers in the very end of lines are the group numbers for refinements of the respective amplitudes and distances.

If due to some reason the numbering of atoms in the input data does not coincide with the already defined numbering (for example, in Z-matrix), the Renumber keyword can be used:

It works in the same way as in the case of reading Cartesian coordinates. Namely, in the example above the following renumbering will be done: O1→O2, H2→H3 and H3→H1. This keyword works with all format types. Note, multiple Renumber keywords can be defined in the same data field and UNEX will process all of them. This can be useful when large amount of atoms must be renumbered and the corresponding list would be too long for a single line.

As already mentioned integer numbers in the very end of lines are interpreted by UNEX as group numbers for amplitudes so that they can be refined. In case of dynamic ED models, the group numbers can be defined only for the first pseudoconformer in the PseudoConfs list (see above). Group numbers for amplitudes of other pseudoconformers are assigned automatically and coincide with those for the first pseudoconformer.

Upon reading ED terms UNEX can automatically check values of parameters for symmetrically equivalent ED terms and symmetrize them, if required. This is done by using the keyword Symmetrize, for example:

In this case UNEX will automatically determine the symmetry of the molecule mol (the geometry of the molecule must be already defined) and the groups of symmetry-equivalent terms. The values of amplitudes, corrections and asymmetry constants for equivalent terms will be symmetrized (averaged) if they differ. In case of significant differences, warning messages will be printed.

For calculation of theoretical molecular contribution to the total electron diffraction intensity scattering factors are required. In chapter Models for ED intensity these factors are denoted as f-functions, which characterize scattering ability of atom pairs. Also in some cases it is convenient to operate with so called g-functions defined as the ratio

where I_at is the atomic contribution to the total electron scattering intensity. In UNEX calculation of all these functions can be done using the EDSCATFAC command:

where with the keyword Lambda the electron wavelength in Å is indicated. Alternatively the energy of electrons can be defined in the form of accelerating voltage (in kilovolt units) using the Voltage keyword. The electron wavelength and accelerating voltage are recomputed in each other internally in UNEX using the formula (4.3.1.33) in [8]. For example the command

calculates scattering factors for mol and the electron wavelength 0.05 Å. This is equivalent to the command

The methods for calculation of elastic and inelastic scattering factors are globally defined using the keywords EDScatFacElMethod and EDScatFacInelMethod, respectively. For electrons with energies 10-100 kV the options pwTab2 and morseTab2 are recommended. In this case UNEX uses built-in tables [8] of inelastic factors and scattering aplitudes and phases defined for the accelerating voltages 10, 40, 60, 90 kV and for s-values up to 60 Å^-1. Two-dimensional cubic splines are used for calculation of required parameters from tabulated values. Note, for accelerating voltages outside the 10-90 kV range the scattering aplitudes and phases are calculated by cubic extrapolation. This may be inaccurate for energies significantly deviating from the stated range. For MeV electrons the recommended options are born1Tab1C1 and morseTab2, respectively. Note, the EDSCATFAC command can be called multiple times for the same molecule. The corresponding functions will be recalculated for requested parameters.

UNEX has a special system for referencing of ED data sets. Each set can contain several data types, including experimental total, molecular and background intensities, atomic scattering and sector function. Also for some of the functions the respective model counterparts can be present. Each set has its unique identifier string, which is defined when reading the data for the first time. The particular commands for working with ED data are described below.

The most important command for reading ED data is EDDATA with the syntax:

where otag and ctag are opening and closing tags of the respective data field. The format of the data is relatively flexible and can be best described by examples, like the one below:

There are two types of lines in the ED data field, keywords and actual numerical data. The most important keyword is Set, which is required for definition of the data set name and for which the data must be read directly from the next coming lines. The name can used later as a data set identifier in different commands and keywords. The other important keyword is Data. It defines the data types to be read. In the example above two types are indicated, the s-values and experimental total intensity. The respective numbers, in the order as defined by the Data keyword, are provided after the keywords line. Below is the complete list of the data types implemented for reading:

The requirements for the input data are as follows:

More than two data types can be introduced at the same time. Here is an example for s-values, experimental total intensities and respective standard deviations:

Apart from Set and Data there are other parameters of ED data sets, which can be defined using the following keywords:

All used keywords must not necessarily be on a single line. You can place them on several lines. This improves the overall readability, for example:

Rotating sector is a special device in electron diffraction experiment for levelling intensity of scattered electrons so that the detector can measure it in wide range of angles without being oversaturated. Thus, the sector modifies primary data, which is mathematically equivalent to a multiplication of the primary intensity by some function. This function depends on the shape of the sector and is called sector function.

In UNEX sector function is decomposed into two parts, an analytical model part and a possible numerical correction. The model part is controlled by the EDSecModelType keyword. For EDSecModelType=rpn the model sector is

for EDSecModelType=sinpn the model is

and if EDSecModelType=const the model is

The parameters A, n and r_max are controlled by the EDSecPrmA, EDSecPrmN and EDSecPrmRmax keywords. By default, the model sector function is EDSecModelType=rpn described by the formula

The other part of the sector function is the so-called reduced sector function. By default it is initialized to constant 1. However, it can be defined in the numerical form and the total sector function is then calculated as

where S is the total sector function, F is the model sector function and f is the reduced sector function.

In numerical form the sector function can be introduced with the EDSECTOR command

The keyword DataType is used for control whether we want to read the actual sector function (sfunc) or the regularization sector function (sfreg). The other keyword FuncType defines the type of input values, which can be total for the total function or reduced for the reduced version, respectively. For example, to input total sector function you need to use:

The data field in the example above contains distances in mm from the center of sector and respective values of the total sector function. The reduced sector function is then calculated from these values based on the current model. To read a reduced sector function use

In the same manner the regularization sector function can be introduced by choosing DataType=sfreg. This function can be used as regularization data in EDSTD:LSQMIN procedure for refinement of sector function from ED intensity data. The model for the regularization sector function is controlled by keywords with the EDSecReg prefix: EDSecRegModelType and others. By default they are initialized to the same values as for the actual sector function.

Together with the values of the sector function it is also possible to introduce respective standard deviations. For this the data field must contain a third column with standard deviations:

Note, if the total sector function is introduced then the standard deviations must also correspond to the total sector function.

After introducing sector function it is possible to smooth it using natural B-splines. This can be done by the command

Here again with the keyword DataType you need to choose the type of data, i.e. the sector function or its regularization.

For determination of sector function it is also possible to use images of the sector device. A sector should be scanned with highest possible spatial resolution. The image must be in 8- or 16-bit grayscale uncompresssed TIFF format. Before processing the image must be prepared so that pixels of the sector surface have values corresponding to exactly black color and the rest of pixels must be exactly while. Intermediate grayscale values are not allowed.

For the processing of the image, several parameters should be defined:

Additionally, particular resolution values can be defined for the image, if they differ from the nominal values. Note, UNEX determines numerically the total sector function, which has values in the range [0,1]. This function is converted to the reduced sector function on the basis of the current sector model. Therefore it is advised to define explicitly the sector model, which fits your sector most closely. Remember, the determined reduced sector function is valid only for the model, which was defined in the processing of the sector image.

Below is an example of UNEX input for processing of sector image.

UNEX implements procedures for ED data reduction, i.e. for transformation of 2D images of measured diffraction patterns to profile curves of experimental electron scattering intensity functions. Images must be in uncompressed 8- or 16-bit grayscale TIFF format with little-endian byte order. For introduction of images in UNEX the Images keyword in BASE must be used. The major procedure for data reduction [23] is started by command

where image is the name of image to be processed.

Before processing it is recommended to clean images. The cleaning procedure is essentially the setting of absolute white grayscale level to pixels, which do not correspond to the diffraction pattern itself (shadows, etc) or represent areas, which should not be processed due to any other reason (defects, etc). The Figure below demonstrates on the left side an initial image of a diffraction pattern with shadows due to construction elements in the diffraction chamber and a resulted image after cleaning. Note, graphical software used for these purposes should not alter values of valid pixels or change the bit depth. Check this before using the software in real investigations!

The other important issue in data reduction is the usage of correct calibration for the sanning device. If the scanner produces uncorrected images the calibration should be taken into account on the stage of data reduction. This includes the spatial calibration, i.e. setting the true resolution values in the input file using keywords ResolutionX and ResolutionY. Note, the deviations of true from nominal resolution values can be different in different scanning modes. This must be carefully investigated for the particular scanning device and scanning modes. The other part of calibration is the correction of output signal. For optical scanners the calibration of optical density is essential. In this case optical wedges are processed for obtaining calibration curve specific for the particular device (and possibly for the particular mode of operation), which is introduced in the input file for the data reduction, see Optical density section. In effect, this kind of calibration must be done for any other type of scanning devices, for example for imaging plate scanners. However, in this case instead of optical density the signal is calculated from pixel values using special formulae and for calibration purposes appropriate standards are required.

The IMAGE:EDPTRNREFINE procedure implements an iterative method [23] for refinement of parameters of diffraction patterns. The maximal number of iterations can by adjusted with the keyword EDPtrnRefIterMax. For the processed image the following parameters should be defined:

Note, some of these parameters can have reasonable default values while other must be defined explicitly. In the refinement a model of the pattern is created, which depends on the following parameters:

Whether parameters of one or other type will be refined depends on the setting of the keyword EDPtrnRefPrm. Intensity values are always refined. The program also detects invalid pixels and sorts them out automatically. The result of this procedure can be checked by inspecting the created image with weights of the pixels.

In the end of diffraction image processing IMAGE:EDPTRNREFINE can create several images in TIFF format with refined profile, background and weights for original image points. The images are created, if the respective parameters were refined and the keyword EDPtrnRefWriteImg is set to appropriate values. The names for images are constructed automatically as <imgname>_profile.tif, <imgname>_bg.tif and <imgname>_w.tif, where <imgname> is the name of the original processed image. Note, these image files are created in the current working directory.

Before describing the methods for processing ED intensity data, it is reasonable to introduce the basic concepts and ED data models implemented in UNEX.

In the independent atom approximation the total electron diffraction intensity can be defined [24] as a sum of two contributions:

where I_mol is its molecular part (i.e. function depending on molecular dynamics and geometry) and I_at is the atomic part — a function depending only on properties of atoms but not on their relative positions. In reality the measured total intensity also contains some additional extraneous additive background B:

Note, the total intensity and all its components are here per unit time, that is in fact they represent flux parameters. In real experiments signal is accumulated over finite time, so in general case the model for the total intensity must include a t-factor proportional to the exposure time:

In this case I_tot can be directly compared with experimental data. If rotating sector is used, it modifies the measured total intensity. Mathematically this can be defined using the sector function S as

where M is the reduced molecular scattering intensity and β is the reduced additive background:

This model of I_tot corresponds to the setting EDItotModel=a1bgr. For details on how sector function is defined and calculated see chapter ED sector function.

The other possibility is

which corresponds to the setting EDItotModel=a2bgr.

In case of using multiplicative background (see the chapter Multiplicative background) the model is set to EDItotModel=mbgr and the total intensity is then calculated as

where k is the scale factor (the keyword ImolSf when introducing ED data) for the molecular intensity M and Φ is the multiplicative background.

Calculation of molecular intensity I_mol depends on the setting of the keyword EDImolAnhTrmModel. If it is equal to morse then the formula is

where ij are the indices for the pair of atoms i and j, f is the scattering factor (see chapter ED scattering factors), l is the mean amplitude of interatomic vibrations, r_a is the thermal-average interatomic distance, a is the parameter of the Morse anharmonic potential. The summation is performed over all pairs of atoms.

For EDImolAnhTrmModel=asym the model is

The symbols here have the same meaning as above, except that the asymmetry constants κ are used. This is the default approximation. Note, the c₃ constants from the cumulant approximation [19] (as printed, for example, by the ElDiff program [21]) are related to κ parameters as κ = c₃/6.

Structural analysis in gas electron diffraction is performed on the basis of the molecular part of total ED intensity. The molecular intensity is obtained by applying the background elimination (extraction) procedure, which can be called simply as background procedure. In UNEX are implemented models for two major types of backgrounds, the multiplicative and additive. The later can be additionally defined in two variants. All of them are described below.

In UNEX there is a possibility for averaging ED intensity curves with the EDDATA command in the AVERAGE mode:

where ed1, ed2 (more is possible) are the identifiers of the ED data sets to be used in averaging; Data is used for indicating the type of data to be averaged, which can be iMolExp (experimental molecular intensity) or iTotExp (experimental total intensity); GenSet indicates the ED data set id for the output averaged data; CalcStdev is the boolean (true or default false) keyword for turning on the calculation of standard deviations.

Note, averaged intensity values are calculated for s values of the first curve ed1 indicated in the command. If points of the other curves are defined not in the same s values then interpolation with cubic splines is used.

In addition to averaging of data and optional calculation of standard deviations this command also calculates the so called experimental R-factors [32]. For each of the curve, participating in the averaging procedure, individual experimental R-factors are calculated as

where is the i-th point of the intensity curve, for which the R-factor is calculated, is the corresponding point of the averaged intensity with weight w_i, N is the total number of intensity points. Here I can be total intensity or sM(s) depending on the type of the averaged data. Individual experimental R-factors show how much each of the curves deviates from the average curve. This information allows to sort out curves of low quality. An average value of individual R_exp is also printed. Regarding weighting, UNEX calculates two types of experimental R-factors:

Note, with CalcStdev=false standard deviations are not calculated so both types of experimental R-factors are equal. Weighting works with CalcStdev=true, when standard deviations for the average curve are calculated.

Next, UNEX calculates total experimental R-factor as

Here summation is performed over all points of all M intensity curves. I can also be total or molecular sM(s) intensity, depending on the averaged data type. The total experimental R-factor allows to represent numerically the overall reproducibility of experimental data and their general quality. Weighted and non-weighted (setting all w_i = 1) total and average experimental R-factors are calculated. Note, the weighted experimental R-factors are calculated even if the standard deviations were not computed in this particular procedure. They could have been defined or calculated earlier for the averaged data set. If uncertain, run PRINT:EDDATA for the averaged data set to see the values of standard deviations used for the calculation of the weighted experimental R-factors.

The advantage of experimental R-factors based on total intensities is that no molecular model is needed for their calculation. However, the absolute values of such R_exp are generally meaningless. They can mostly be useful for comparison of data sets produced only by the same experimental setup. In contrast, experimental R-factors on the basis of sM(s) curves are directly comparable with structural R-factors:

where and are the experimental and model sM(s), respectively.

R_str indicates the level of disagreement of the model with experimental data, while R_exp indicates reproducibility of the experimental data. There can be several situations:

Note, if both R_str and R_exp are large, then something went completely wrong, first of all in experiment and/or in data reduction. Also note that weighted R_str (named wRd in UNEX output) should be compared with weighted R_exp, likewise non-weighted R_str should be compared with non-weighted R_exp.

Below are several examples of averaging commands.

Another possibility of converting multiple ED curves into a single curve provides the COMBINE mode of the EDDATA command:

the identifiers and keywords have here the same meaning as in the AVERAGE mode. However, in contrast to AVERAGE, where output s points are taken only from the first input curve, the combining procedure creates a curve with s-values present in all input data sets. Thus, curves with different s-ranges can be combined together. For the overlapping areas averaged values are calculated. If standard deviations were initialized for the respective input data sets, weighted averaging is used, where weights are calculated as inverse squares of the respective standard deviations. The Figure below demonstrates how COMBINE works for two experimental sM(s) curves obtained from different nozzle-to-detector distances. The respective command was

Note, in COMBINE experimental R-factors are calculated in a similar manner is in AVERAGE (see above). There are, however, some peculiarities. The weighted R-factors are also calculated if standard deviations were not requested for calculation. However, in contrast to AVERAGE, standard deviations are still calculated internally, used for computation of wRexp, but are not saved for the averaged data set. Also it should be noted that standard deviations are set to 1e99 if only one data set has contribution to the combined data in the respective point.

The EDDATA command can be used in other different modes for ED data processing.

For example, in the mode MODIFY the data can be respectively modified:

where ed1 and possibly ed2 and so on are identifiers of ED data sets to be processed, dtype is the type of data to be modified (currenly allowed iTotExp and iMolExp), end mtype is the type modification, which can be one of

Note, the only modification type currently available for iMolExp is smooth.

The other available mode is RESPCOR, which is used for correcting experimental total intensity functions with the detector responce function. The syntaxt is simple:

Several data sets can be processed at once. The response function must be already available in UNEX. It can be obtained by refinement or introduced with the EDRESPFUNC command, see Response function for details and examples.

The COPYMODEL mode is used when it is required to copy model data to the experimental data, thus making them equal. The syntax is as follows:

where dtype can be iTotExp and iMolExp, for copying to experimental total and molecular intensities, respectively. Several data sets can be processed at once.

The ADDNOISE mode, as the name says, implements the adding of noise to the existing data:

where dtype can be iTotExp and iMolExp, experimental total and molecular intensities, respectively; ptype is the type of the probability density function, for which the only currently implemented option is normal.

Finally, there is a SET mode, which is useful for changing different settings of ED data sets on the fly when UNEX runs:

where in place of the word Keywords you can define the actual keywords with respective required settings. The keywords here can be exactly the same as at the reading of ED data sets with the command EDDATA:READ. For example, the following

will change in the data sets ed1 and ed2 the model for the total intensity to a2bgr.

Radial distribution functions in UNEX are calculated and printed by the EDRDF command:

Optional argument(s) of the command form a list of one or more ED intensity data sets with initialized molecular intensity functions. The calculation is essentially a sine-Fourier transformation of the respective experimental and model molecular intensity curves:

If several curves are provided in the list of arguments, they are concatenated before Fourier transformation, for example

Note, the curves must have common range of s-values. The concatenation procedure includes relative scaling of curves, re-interpolation to common argument values (if required) and weighted averaging in common ranges of argument. Next, there are three general modes for calculation of radial distribution functions, which directly influence the minimal and maximal values of integration argument s. The modes, controlled by the EDRdfType keyword in BASE, are as follows:

Note, the concatenation of model and experimental sM(s) curves in classic and modern types of RDF requires some overlap of these functions. The extent of the overlapping can be adjusted using keyword EDRdfNConcat.

Below are some examples of RDFs for benzene using different options of EDRdfType:

Here the variants A, B and C correspond to the settings EDRdfType=modern, EDRdfType=classic and EDRdfType=old, respectively.

Below is the graphical representation of the influence of damping function on the RDF in case of benzene when EDRdfType=classic and experimental data available only up to 30 Å^-1. If the damping is turned off, i.e. EDRdfDamp=0.0, the RDF has multiple false peaks. An optimal value of damping factor removes these peaks. Too large value of the damping factor increases widths of true peaks so that the resolution of RDF is too low.

The cases A, B and C were obtained with the settings EDRdfDamp=0.0, EDRdfDamp=0.0025 and EDRdfDamp=0.01, respectively.

The next issue in calculation of RDF is connected with representation of contributions of different terms in sM(s) functions. In a crude approximation the contribution of a pair of atoms to diffraction pattern is proportional to the product of their atomic numbers. The respective RDF in this case can be easily analysed. In reality, however, contributions of atomic pairs to diffraction patterns are not constant on the s-scale and are not even linear (this property is characterized by scattering factors). As a consequence, the calculated RDF is difficult to analyze. Fortunately, ratios of scattering factors for different types of atoms are much closer to constants than the scattering factors themselves. UNEX provides a possibility to divide the integrated molecular intensity by a scattering factor in a form of g-function, which is controled by the EDRdfModGf keyword in BASE. This can improve the appearance of the obtained RDFs. By default for this purpose UNEX chooses a g-function for the pair of atoms with maximal product of atomic numbers. Note, however, that this logic can fail in molecules containing atoms with very different atomic numbers. In this case some g-functions can go through zero and change the sign. Accordingly, RDF cannot be obtained by integration of molecular intensity modified by such a g-function. In this case an optimal g-function can be chosen manually by using EDRdfModGfAtoms keyword.

In case of benzene the influence of EDRdfModGf is as follows:

In these examples the variant A has been obtained by using the combination of keywords EDRdfModGf=true and EDRdfModGfAtoms=C;C, variant B only single keyword EDRdfModGf=false and for C again a combination of keywords EDRdfModGf=true and EDRdfModGfAtoms=C;H.

For obtaining RDFs integration is done numerically. For this UNEX implements two methods, simple trapezoidal and more accurate but slower Romberg method. In most cases the first method is accurate enough and is used by default. Switching between integration methods is done by EDRdfIntegMethod keyword in BASE.

Regarding r-values, for which RDFs are calculated, two schemes are implemented in UNEX:

The RDF defined above as integral F(r) is essentially the distribution P(r)/r, where r is the distance between atoms and P(r) is its distribution function. The first moment of the function P_ij(r)/r for a particular pair of atoms ij is the r_a type of thermally averaged distance between these atoms. Thus, RDFs calculated as described above show peaks centered at r_a distances. There is, however, a possibility to obtain RDF defined as P(r), which is more natural. For this, UNEX can multiply the integral by r, see EDRdfMultR keyword. In this case the peaks are centered at r_g distances between atoms. Note also that this procedure naturally increases the difference curve (difference between model and experimental RDFs) proportionally, so this should not be misinterpreted as a worsening in the model fit. Below is such an example using data for Ph-CH₂-CH₂-CH₂-Se-CF₃ molecule. Note again, both RDFs were obtained for exactly the same experimental data and model. The advantages of the P(r) function are clearer physical meaning and more distinct visibility of contributions from terms with large interatomic distances. In contrast, the P(r)/r function effectively hides discrepancies between data and model, which hinders analysis. Therefore in UNEX the default setting is EDRdfMultR=true so that P(r) RDFs are generated.

In the example above the varients A and B were obtained with the settings EDRdfMultR=true and EDRdfMultR=false, respectively.

If your experimental molecular intensities have meaningful standard deviations it is possible to calculate errors of experimental RDFs by switching the EDRdfCalcStdev keyword on. Standard deviations for sM(s) can be defined in input file as absolute values, calculated in averaging procedure or in background procedure from respective errors of total intensity functions. Standard deviations for sM(s) are also estimated in LSQFUNC:MINIMIZE but should be used with care in case of large R-factors. Note that the calculated values of standard deviations for RDFs only represent random errors propagated from respective errors of sM(s).

The default method for calculation of standard deviations uses error propagation formula and numerical differentiation of sM(s) functions. For large models the calculations can be (very) time consuming. There is an alternative procedure which uses the Monte-Carlo method. This can be activated by setting the keyword EDRdfMCIter to some positive integer value, indicating the number of iterations. It is recommended to investigate the convergence of the calculated results with respect to the number of iterations. In some cases the optimal value of EDRdfMCIter can be from several hundreds to several thousands.

Below in Figure the simulated molecular intensity functions for 1,2-dichloroethane (1:1 mixture of anti and gauche conformers) are shown. Random Gaussian noise, with standard deviations 0.03 for the curve above and 0.025 for the curve below, was added to the simulated experimental data.

These data were used to calculate model and experimental RDFs with respective standard deviations. The obtained data are plotted on the Figure below. Note, the calculation was done with EDRdfMultR=true, that is RDFs corresponding to P(r) were calculated. Therefore oscillations of the difference curve and the standard deviations increase when r increases.

Alternatively UNEX can calculate more traditional RDFs of type P(r)/r by switching the EDRdfMultR keyword off. Usually in this case standard deviations are distributed approximately equally along r scale. The Figure below demonstrates P(r)/r for 1,2-dichloroethane calculated from the simulated sM(s) data shown above.

UNEX can process ED intensities of gas standards. In most cases this is done in order to refine (i.e. calibrate) electron wavelength. The respective command is EDSTD:

Here method can be SCANLAM, REFINELAM or LSQMIN. Also in the command there must be defined one or more identifiers of intensities, which should be processed. For each intensity the type of ED standard can be defined with the local keyword Std, otherwise default value from the global keyword EDStdDefType will be used. In most cases initial value of the electron wavelength (keyword Lambda in definition of intenity curves) and distance from nozzle to detector (keyword NtoD) must be defined. It is also recommended to set the sector-to-detector distance (keyword StoD) to an appropriate value if sector device was used for obtaining experimental data and sector function is used in the procedure.

The first method SCANLAM does searching of the best electron wavelength by scanning. The control keywords for this method are EDStdScanIter, EDStdScanLamMin and EDStdScanLamMax.

The other method REFINELAM searches the best electron wavelength using golden section method. In contrast to the simple scanning it recalculates background on each iteration, which increases the overall accuracy of the obtained electron wavelength. The most important keywords for this method are EDStdRefLamIterMax and EDStdRefLamTol.

Note, the type of model for total intensities in these both methods can be chosen using individual for each intensity curve keyword ItotModel. In fact this determines the type of background calculated for the intensities. The valid options are mbgr, a1bgr and a2bgr. The background and respective experimental sM(s) are also not calculated if ItotModel is not defined. In this case the experimental sM(s) must be defined and available from some other source, for example from input file. The approximation for background lines can be defined using global keyword EDBgrAprxType. The flexibility of the lines can be controlled by defining the maximal number of inflection points with the keyword BgrSplNInflMax for each curve individually, or with the global keyword EDBgrSplNInflMax. If polynoms are used for background approximations, then the relevant keywords are local BgrPolPow and global EDBgrPolPow. Depending on the type of background scale- or t-factors can be refined if EDStdBgrRefScaleIterMax is greater than zero.

The other option for the method is LSQ [33]. In this case the least-squares method is used. It refines parameters of total intensities by minimizing a functional, which is generally defined as

The summation in the first term is performed for all points of all intensity curves processed simultaneously. The second term is for regularization of the refined sector function, if the keyword EDStdSecRegAlpha is set to non-zero value and a regularization sector function is defined with the EDSECTOR command. The third term is for regularization of refined background functions. For this the EDStdBgrRegAlpha keyword must be set to some non-zero value. The regularizing value itself is defined by the keyword EDStdBgrRegValue. The fourth term is for the additional control of the background flexibility, if the keyword EDStdDBgrRegAlpha is set to non-zero value. In fact this is a sum of second derivatives of backgound values of all curves in all points.

Again, the used model for the total intensity depends on the setting of the ItotModel keyword for each intensity curve. In the least squares method the valid options are a1bgr and a2bgr. For details see Models for ED intensity. In the first model background β is refined, in the second case background B is refined. The reduced sector function is modelled numerically as a set of its values at particular r-values at the sector plane. The particular set of r-values with explicit initial approximation for the reduced sector function can be defined with the EDSECTOR command. Alternatively UNEX can automatically initialize initial reduced sector function, see keyword EDStdSecInitRStep. Note, in any case a model sector function must be defined, see EDSecModelType and EDSecPrm* keywords. Backgrounds β or B are modelled as Chebyshev polynomials. The order of polynomials can be defined for each curve individually using the local StdBgrModelPow keyword. Normally an initial approximation for the background is obtained by fitting the polynomial to a background, which is obtained by calculating the model. By setting EDStdLsqBgrInit=data, the source of initial background will be the values in the respective data set. The types of parameters to be refined is determined by the EDStdLsqRefPrm keyword.

Diffraction intensities of the following molecules can be processed in UNEX as gas standards (default standard values are taken from the cited papers):

Currently used standard values of parameters for these molecules can be printed with the command

It is also possible to define a custom set of standard parameters for each standard molecule with the EDSTDPRM command:

Here stdtype is the type of standard, one of the following: CCl4, C6H6, CO2, CS2. The keyword Format is optional, the only available format is unex and it is assumed by default. In the input file between tags otag and ctag must be defined types of terms and their parameters: r_a distance, amplitude l and asymmetry (or Morse) constant. Note, the last parameter should correspond to your setting of the EDImolAnhTrmModel keyword. By default it is EDImolAnhTrmModel=asym, so asymmetry parameters are expected. Model molecular intensity functions are calculated from the introduced parameters using the respective approximation as described in chapter Models for ED intensity. In these calculations multiplicity factors (number of equal terms of a given type in the molecule) are used automatically. They are predefined for each term in each standard molecule in UNEX.

Here are examples of the EDSTDPRM command:

UNEX can make use of and process rotational constants of molecules and related parameters. The definition of all these quantities is done in the fields of respective molecules as described above. Here we introduce the models implemented for rotational constants and some basic operations with them.

In UNEX it is possible to do a simple vibrational analysis. Direct vibrational problem — calulation of harmonic vibrational modes and frequencies can be solved using the command MOLVIBFREQ as

where the keyword Method defines the method of calculation. At present it has the only available option diagf2cmw. The procedure diagonalizes the matrix of harmonic force constants in mass-weighted Cartesian coordinates. Note, the force constants as well as the respectively oriented Cartesian coordinates of atoms must be already available in UNEX. For this, for example, the commands MOLVIBF2C and MOLXYZ can be used. Results of the procedure can be printed using the PRINT:MOLVIBMODES command (see below).

UNEX can calculate thermodynamic functions for systems consisting of pure substances. For this the MOLTHERMO command can be used:

The keyword Method has the only option stat, which indicates the usage of tatistical thermodynamics theory [41]. Other keywords are described below. Before running this command geometry and vibrational frequencies must be already defined for the respective molecule. The frequencies can be calculated or introduced with the MOLVIBFREQ command (see Vibrational frequencies). Depending on the ThermoModel setting of the molecule the calculation can be performed in different ways. In the simplest case, ThermoModel=sRRHO, UNEX uses the model of ideal gas, assumption on uncoupled translational, rotational and vibrational motions, rigid rotator and harmonic oscillator (RRHO) approximation [42]. Note, the frequencies may be scaled by using the ThermoFreqScale keyword, which turns the approximation effectively into the anharmonic oscillator, respectively. The other option, ThermoModel=msRRHO-1, utilizes the so called modified scaled RRHO method by S. Grimme [14], with a modified procedure for the calculation of the vibrational entropy. Two keywords are related to this method, ThermoMSRRHOWCutoff1 and ThermoMSRRHOWAlpha1. Note, this method was also known as quasi-RRHO [13]. The last option, ThermoModel=msRRHO-2, in addition to the entropy correction (as in msRRHO-1) also uses similar correction to enthalpy as described in [15]. The respective control keywords are ThermoMSRRHOWCutoff2 and ThermoMSRRHOWAlpha2.

Thermodynamic functions are calculated for conditions (temperature and pressure) defined by the optional keywords to the command (see below) or by global parameters. In calculations it is also assumed that only the ground electronic state is populated and other states are not achievable. The contribution of the ground electronic state is determined by the spin multiplicity and can be defined using the SpinMult keyword in the field of the respective molecule.

Possible optional keywords of the MOLTHERMO:CALC command are as follows

For example, the command

calculates thermodynamic functions for the h2o molecule at 500 K and default (standard) pressure. All types of motions will be taken into account, except for translations.

On the output are printed inner energy U, enthalpy [H(T)-H(0)], entropy S, Gibbs free energy G, constant volume heat capacity Cv and constant pressure heat capacity Cp. The particular contributions to the thermodynamic functions and to the molecular partition function Q from different types of motions are also printed. If the electronic energy has been defined for the molecule (see the EnergyEl keyword) then total values for the thermal energy, enthalpy and Gibbs free energy are printed.

Note, small vibrational frequencies lead to large errors in calculated thermodynamic functions within standard RRHO approximation. Depending on the application, it may be reasonable to ignore such frequencies by using the keyword ThermoFreqCutoff. However, a more universal way for solving this problem is to use the msRRHO methods.

To the processing of data samples we can ascribe their simulation. This can be performed using the DATASAMPLE command in SIMULATE mode:

where mdl must by the model for the simulated data. At present the only available model is Ishigami [43]. For the model must be defined parameters using keywords with Prm prefix. Ishigami needs two parameters, which can be introduced as for example

Next, for variables must be defined probability destribution functions using keywords with prefix RND. Ishigami has tree variables, they can be defined as

Finally with the keyword NValues there must be defined the number of values to be generated for the model function. Optional keywords are:

Refinement of all kinds of parameters in UNEX is closely associated with the term group. A group represents a list of parameters tied by particular constraints. Most often the constraints are fixed differences between values of parameters within each group. In case of ED vibrational amplitudes there is also a possibility to fix their ratios within each group instead of differences (see the LsqEDTrmAmplSfRef keyword). The number of parameters in a group is not limited. However, only particular kinds of parameters can be grouped together. Formally a group can also consist of only one parameter. In this case the respective parameter is not tied to any other parameter in refinement procedures. Groups are defined by unique integer numbers. Each parameter can be defined with its respective group number. Several parameters with the same group number are combined together to a single group and refined with fixed constraints. By default parameters are defined without group numbers, which is the same as to assign them the group number 0. If you want to refine parameters, you have to define their group numbers larger than zero explicitly. For refinement procedures the amount of variables is equal to the number of active groups. Thus, multiple parameters in a group in fact act as a single parameter in least-squares refinement. Consequently they share the same estimated standard deviation as a group. Note, this is not equivalent to a situation when the parameters are statistically independent and have their individual standard deviations, even if they are numerically equal!

Below is the list of parameter types, which can be refined in UNEX.

Automatic or semi-automatic grouping of ED term parameters can be done using the EDTERMS command as

At present the only available option is ParType=ampl, meaning grouping of vibrational amplitudes. Two methods are available, manrint and rdfpeaks.

For using the first method, manrint, with an additional keyword RInterval must be indicated range(s) of r_a distances. The grouping is then done on the principle that terms within a particular range belong to one group. For example, the command

will group amplitudes in the terms with r_a distances in the range [1.0,2.0) Å and another group will be created for the range [2.0,3.0) Å. The numbers of groups will be assigned automatically. Use keyword FirstGroup if you want to control the group numbers explicitly, for example

will create two groups, 200 and 201.

Another possibility provides Method=rdfpeaks. This procedure calculates internally a radial distribution function (RDF) for the current ED model, determines ranges of r_a distances belonging to particular peaks of RDF and then performs grouping on the basis of these ranges. For example:

Accordingly, this method requires completely initialized ED model. Note, in case of ED models of molecular mixtures it is reasonable to apply the same grouping scheme to all molecules at once. This can be done by indicating the addtional molecules to be processed. For this purpose use the keyword AddMols, for example:

In real practice it is strongly advised to analyse the performed by this procedure grouping and adjust it manually, if required. Also note, both methods perform grouping only for those amplitudes, which did not belong to any group before.

In UNEX the main command for parameter refinement is LSQFUNC, which means least-squares functional. This command has different modes of operation. Below they are described in detail.

The most important refinement procedure is the direct minimization of the target least squares functional starting from current values of model parameters. This is done in the MINIMIZE mode, with the common syntax

Here the type of the LSQ functional must be provided, the data identifiers should be defined in case of ED (see examples below) and different additional settings can also be used. There are several types of functionals:

Additional settings can be defined as usually in the format Keyword=value. The available keywords are

In its most general form the complete least squares functional is represented as

Here the first, second, third and fourth terms correspond to EDSMS, ROTCON, REGPRM and MOLGEOMRST types of the functional, respectively. The global weighting factors α_ED, α_rot, α_reg and α_rgp are defined by the keywords LsqFuncEDImolAlpha, LsqFuncRotConAlpha, LsqFuncRegPrmAlpha and LsqFuncMolGeomRstAlpha, respectively. Depending on the available data and the problem these parts of the general functional can be used solely or in any combinations.

If EDSMS is given, particular ED intensity curves must be indicated explicitly for constructing the functional, for example

Individual weights w_i for the sM(s) data points are calculated automatically from their standard deviations as w_i=σ_i^-2. The other types of functional do not require explicit indication of their data. ROTCON automatically includes all defined rotational constants for all molecules and their isotopologues (isotopomers), see the keywords RotAExpVal, RotBExpVal and RotCExpVal. The weights for them are calculated in the same manner as for ED data from respective standard deviations defined with the keywords RotAExpStdev, RotBExpStdev and RotCExpStdev.

The functional REGPRM uses data, which can be read in using the respective command REGPRM. The syntax of this command is as follows:

The only available mode is READ, which means the reading of the data as in the example:

Here in the first column the group numbers are indicated. In the second and third columns regularization values and their individual standard deviations are provided. In the equation above the regularization values correspond to p_k^reg, while the weights w_k are calculated from the introduced standard deviations as w_k=σ_k^-2.

Note, the regularization is applied to the first parameters in the groups, so the regularization values must be appropriate. The other parameters in the groups are regularized automatically to the same extent due to rigid constraints. Regularization must not necessarily be used for all refined parameters, i.e. restraints can be applied only to some selected groups. With REGPRM it is possible to define regularization parameters for groups, whose parameters are currently not refined. In this case the respective restraints are ignored and not included in the least squares functional. This has been implemented because in LSQFUNC:MINIMIZE and related procedures different groups of parameters can be processed, whereas the list of the regularization parameters is global. The units of the regularization values must be the same as the units used for introduction of respective model parameters in UNEX input. For parameters of potential functions internal UNEX units are expected. They can be checked by printing data with the PRINT:MOLPEFUNC command.

MOLGEOMRST functional is built on the basis of geometrical parameters of molecules. The allowed types of parameters are interatomic distances, angles, dihedral (torsion) angles and out-of-plane angles. For their definition see section for geometrical parameters in chapter Data printing. The restraining data are read in for particular molecules with the MOLGEOMRST command as in the example:

Each line starts with the type of the parameter. The possible types are distance, angle, dihedral and o-o-p (for out-of-plane angles). Next, indices of atoms must be provided. The numbering starts from 1. Finally, values and respective standard deviations for the defined parameters are given. Note, the standard deviations are optional but it is recommended to indicate them explicitly. Otherwise they are assumed to be 1.0. The units for distances and angles are Angstroms and degrees, respectively. In LSQ functional the weights are calculated from the defined here standard deviations σ as w_l=σ_l^-2. Note, for models of mixtures each molecule can have an individual set of restraining geometrical parameters. All of them are participating in the respective sum of the LSQ functional given above. The prefactor α_rgp is thus the same for all sets. Also note that the restraining geometrical parameters should not necessarily be equal to the parameters in definition of the initial molecular geometry. Distances can be given for chemically non-bonded atoms.

In the beginning of the LSQFUNC:MINIMIZE procedure the information on data for constructing the LSQ functional is printed. This includes the number of data, α values, etc. If electron diffraction intensities are used, then the structural resolution and maximal structural distance are estimated. The former is calculated as

where s_max and s_min are the maximal and minimal s-values for which experimental ED intensity values are available. The maximal structural distance is calculated as the Nyquist frequency due to the Whittaker–Nyquist–Kotelnikov–Shannon sampling theorem [56, 57]:

where Δs is the average spacing between adjacent intensity data points in Å^-1. The r_max value shows the largest interatomic distance, which can possibly be determined from the current electron diffraction data set. However, bear in mind, that inverse problems with real experimental data may be not enough sensitive to such terms with large distances.

Minimization of the LSQ functional can be done using two methods:

The particular method can be chosen with the global LsqMethod keyword. Both methods are iterative, the maximal allowed number of iterations is defined by the keyword LsqIterMax. Iterations stop in several cases:

In UNEX there are two different weighting schemes in LSQ analysis: relative and absolute. They influence calculation of standard deviations of refined parameters. With absolute weights the matrix of covariances (with squares of standard deviations as diagonal elements) is obtained directly as inverse of the respective normal matrix. In case of relative weighting the calculated cofactor matrix (the inverse of the normal matrix) is multiplied by the factor χ²/v, where χ² is the LSQ functional value and v is the number of degress of freedom, calculated as the number of data points minus the number of refined parameters v = N_data - N_prm. The switching between absolute and relative weighting can be done using the LsqAbsWeighting keyword.

Depending on settings LSQFUNC:MINIMIZE can print different types of data for information on minimization status, properties, convergence and so on:

After the minimization several blocks of data are printed:

Several types of LSQ functional can be combined in LSQFUNC:MINIMIZE. For example, the following command

refines parameters from rotational constants and indicated ED data sets simultaneously. In the same manner three types of data can be used

or with restraining geometrical parameters

Any other combinations are also possible.

As has been already stated, refinement of particular parameter groups can be turned on or off directly in the command. By default all parameters with group numbers greater than zero are refined. If group numbers are defined explicitly in LSQFUNC:MINIMIZE then only parameters in these groups will be refined. The following example demonstrates how to refine parameters only in groups 1 and 2.

The other possibility is to prohibit refinement of parameters in particular groups. In the following example parameters from all groups except 5 are refined:

Several groups can also be excluded from refinement:

Particular group numbers and ranges can be used:

Combinations of the permisive and prohibitive keywords can also be used:

In complex LSQ functionals the factors α_ED, α_rot, α_reg and α_rgp should have appropriate values. The problem is that there is no single clearly defined criterion for them. Usually α values are adjusted according to specific requirements of a particular investigation (see discussion of the problem in [63]). There are, however, some heuristic criteria. One of them is implemented in UNEX [64] (a more detailed description is given in [9]). The respective mode is OPTALPHA:

The syntax here is the same as for MINIMIZE. In fact this is an iterative procedure, which internally starts MINIMIZE on each iteration. Note, the procedure is implemented only for some cases when only two types of functional combined together.

The described above command for minimization of LSQ functionals implements the main procedure in UNEX for these purposes. A more complex method is provided by the IRMINIMIZE mode of the LSQFUNC command. In contrast to MINIMIZE it iteratively modifies the weights of experimental data using the bisquare scheme of Tukey [65, 66]. Accordingly, standard deviations of experimental data are adjusted. The weights are calculated iteratively from respective residuals. In fact IRMINIMIZE internally starts the MINIMIZE procedure on each iteration, refines model and updates weights of all data points. This procedure is repeated until the weights are converged or the limit for the number of macro iterations is achieved (see the LsqIRIterMax keyword). The syntax is as following:

Currently reweighting is implemented only for ED molecular intensities and rotational constants.

The described above MINIMIZE and IRMINIMIZE are local methods for minimization of LSQ functionals. This means that they typically converge to a local minimum depending on starting approximation. With these methods there is no possibility to know exactly whether obtained solution corresponds to the global minimum on the functional (hyper)surface. To solve this problem in UNEX there are two additional methods as modes of the LSQFUNC command. The first one, SCAN, implements systematic scanning of LSQ functional by testing different values of parameters on a defined grid. The syntax of the command is as follows:

Here the functional and data are defined exactly in the same manner as in the MINIMIZE mode. Keywords are described below. Note, you need to define the grid of parameters to be used in the scanning procedure. This is done using the LSQSCAN command, for example:

This defines a two-dimensional scan. In each line first goes the refinement group number, then the range of the respective values for the first parameter in the group. In the example above the first parameter in group 1 will be scanned in the range from 1.76 to 1.78 with 100 steps. The other parameters in this group will be automatically adjusted using fixed constraints as usually. In the same manner the second scanning dimension is defined. In total, the two-dimensional scan will do 101x101=10201 calculations of functional for different combinations of parameters. If the total functional value has decreased after the scan, then UNEX reports values of parameters corresponding to the lowest functional value and applies them to the model.

The procedure in LSQFUNC:SCAN finds global minimum of functional within defined limits for values of parameters and with accuracy determined by scanning step size(s). The problem is, however, that the required number of scanning points scales as S^N, where S is the number of steps for each parameter and N is the number of parameters or groups of parameters. Thus, the total number of points increases very quickly with the number of scanning dimensions. To avoid this problem UNEX implements a randomization method RAND for searching of global minimum. The syntax of the respective command is very similar

For the definition of parameters use the LSQRAND command:

The format is similar to that of the scanning, except that the type of distribution must be provided (the only option now is uniform) and the number of steps is omitted.

In the scanning or randomization UNEX creates a data sample and continuously writes the generated values into its file. If the file name was not defined before, then it is automatically constructed as <basename>_<dsname>_<seed>.dat and written in the current working directory. By default the <basename> is lsqscan or lsqrand. <dsname> is the name of the created data sample, which is generated automatically by default. Finally, <seed> is the seed number used for initialization of random number generator. All these parameters may be defined explicitly using corresponding keywords.

The keywords specific for the SCAN and RAND modes of the LSQFUNC command are (prefix Surv stands for surveying):

Determined in inverse problems parameters are random numbers per definition, if they are refined from real experimental data. Accordingly, each refined parameter is associated with its own probability distribution function (PDF). In the simplest and the most common case it is assumed that the PDF is the normal distrubution, which is characterized by its position (i.e. the value of the parameter) and the standard deviation as a measure of its width. In each least-squares refinement standard deviations and correlation factors are calculated for parameters. They are accurate only in the simplest case, when

In real structural investigations, however, none of these conditions are fulfilled and the problem of determining parameter uncertainties is getting (much) more complicated. In UNEX is implemented a method for solving these issues by using the Monte-Carlo simulation approach [67]. In this way it is possible to investigate how uncertainties in experimental data and model parameters are propagated into refined parameters. More precisely speaking, it is investigated how PDFs of experimental data and of model formal constants are propagated into PDFs of refined parameters.

The former must be introduced from outside and defined in UNEX, the latter are then determined and calculated by special methods. Definition of PDFs for input data and for (molecular) parameters is performed using special keywords and commands. There are three groups of special dedicated keywords, usually ending with PDFGrp, PDFType and PDFPrm. PDFGrp keywords (for example, RotAExpPDFGrp) are used for assignment of group numbers to respective PDFs. Parameters within one PDF group are sampled in a constrained manner, that is they are statistically not independent. In contrast, parameters sampled in different PDF groups are statistically independent. PDFType keywords (for example, RotAExpPDFType) define the type of PDF and the meaning of respective PDFPrm keywords (for example, RotAExpPDFPrm1 and RotAExpPDFPrm2). In UNEX several types of PDFs are implemented, so the available options for PDFType keywords are as follows

The Monte-Carlo method for calculation of PDFs of refined parameters is started by calling the LSQFUNC command in the MCMINIMIZE mode:

The syntax of the command is similar to that of MINIMIZE mode described above. In fact, the MCMINIMIZE procedure calls MINIMIZE internally. However, it is recommended to run Monte-Carlo simulations for already refined models. Parameters and data are sampled randomly from their respectively defined distributions and for the newly generated model and data a least-squares method is started for minimization of the defined in the command functional. The refined values of parameters are saved in a data sample. These steps are performed multiple times in a loop. Thus statistics for refined parameters are collected and the procedure is repeated until convergence or until the maximal allowed number of cycles is reached.

The following data can be randomized:

The initial state of the random number generator can be controlled using the global keyword LsqMCSeed or the local keyword MCSeed. Set this parameter to a particular integer value if you want to obtain reproducible results. Otherwise it is initialized automatically in a pseudo-random manner so that you get numerically different results in each run. However, if the procedure is well converged the results must be very similar.

Note, even in the MCMINIMIZE mode you can use keywords of the LSQFUNC command applicable in the MINIMIZE mode. This is implemented intentionally since LSQ minimization is started internally in MCMINIMIZE. There are, however, keywords specific for the MCMINIMIZE mode:

In order to be able to randomize data and parameters, they must belong to PDF groups. The assignment of PDF types, parameters and group numbers for some model parameters can be done using dedicated keywords with the suffixes PDFType, PDFPrm and PDFGrp, as described above. For other model parameters and data, special commands must be used, which are described below.

PDFs for regularization parameters can be defined together with the regularization values using the already available REGPRM command:

In this case the field of data must be in the format like in the example below:

Here each line contains regularization data as usually in the first three positions (described elsewhere), and the next items define PDFs. In the shown example the regularization parameter for the refinement group 1 has the PDF in group 101 with type shNormal and respective parameters 0.0 and 0.02. Similarly, the regularization parameter for the group 2 has the PDF in group 102, the type of the PDF is also shNormal and its parameters are 0.0 and 2.00.

For introducing PDFs of Z-matrix parameters there is a specially dedicated command ZMATPDF:

The format of the respective data field is as follows:

With the local keyword PDFType the type of PDF is defined. In each of the next lines the name of the already defined Z-matrix parameter is indicated with corresponding parameters of its PDF and the PDF group number in the very end. For example, the Z-matrix parameter RCH has a PDF of type shNormal with parameters 0.0 and 0.005, which belongs to the PDF group 10. Note, the input units are here the same as at introducing Z-matrix parameters with the ZMATRIX command.

Currently active molecules are printed by the command

For information about loaded images you can use

Brief information about hardware and operating system is printed by

The command below prints symmetry elements for mol and respective point group. Geometry for mol must be already defined.

The command prints experimental and model rotational constants for mol. Model values are calculated for the current geometrically consistent structure of mol. Experimental values are printed as defined in the input. Additionally, for each rotational constant respective corrections (defined earlier in the field of the molecule), experimental standard deviations, differences between experimental and corrected (using input corrections) model values and errors are printed. The errors are calculated on the basis of standard deviations of refined molecular parameters using error propagation formula. In the end the values of root-mean-square deviation (RMSD) and weighted RMSD (WRMSD, taking into account experimental standard deviations) are calculated and printed. Note, (W)RMSD are printed only if at least one experimental value is not zero.

Harmonic force constants in Cartesian coordinates are be printed by

where the optional keyword Format can accept values matrix (this is default), shrink and gamess.

Cubic force constants in Cartesian coordinates are printed as

where the only available format is blocks. The number of columns in each block is controlled by the global keyword PrintF3cBlockCols.

Cubic force constants in normal coordinates can be printed using the command

The optional keyword Format can be set explicitly to idxval. By default the constants are printed in internal units, Hartree amu^-3/2 Bohr^-3. However, it is possible to get the values in cm^-1 by using Units=cm. By default it is Units=hartree-amu-Bohr.

Vibrational modes with respective frequencies can be printed as

UNEX can prepare input data for ElDiff, the program for vibrational spectroscopy and electron diffraction written by Igor Kochikov [21].

The first example prints data for calculations in ElDiff using Cartesian coordinate system. The second command prints data for calculations in internal coordinates. Note, to be able to print such data there must be introduced harmonic and optionally cubic force field(s) and Cartesian coordinates for the respective molecule.

Particular geometrical parameters of molecules are printed by calling PRINT:MOLGEOMPRM command with appropriate keywords:

where type can be one of distance, angle, dihedral and o-o-p (for out-of-plane angles), and list must contain index numbers of two, three or four atoms, depending on the type of parameter. For example:

The numeration scheme is as in the image below

UNEX prints three types of distances, r_c, r_a and r_g. In UNEX output they are indicated as r_c, r_a and r_g, respectively. r_c is the geometrically consistent distance as calculated from Cartesian coordinates. In ED structural refinements its definition is closely related to the type of vibrational corrections. If the corrections are (r_e - r_a) then the r_c distances are in fact r_e. In refinements from rotational constants the definition of r_c depends on the type of corrections for these constants. If B₀ are used without any correction then the refined r_c are in fact r₀. There can be also other possibilities, depending on details of the structural analysis. r_a and r_g are two kinds of thermally averaged distances, related to ED method. r_a can be calculated from r_c internally by subtraction respective vibrational corrections. r_g distances are calculated from r_a and respective vibrational amplitudes l using the approximation

For all types of geometrical parameters errors are calculated (see explanation above) and printed. By default they correspond to estimated standard deviations, but also can be modified by a factor defined by the PrintStdevFac keyword.

There is also a possibility to generate automatically a complete set of internal geometrical parameters and print their values with respective errors. This can be done by calling PRINT:MOLGEOMPRM without keywords:

In this case UNEX tries first to identify bonds and then to generate all other parameters based on the connectivity information. Two atoms are assumed to be connected with a bond if distance between them is less than the sum of their covalent radii [68] plus some fraction of this sum (see the MolGeomGenBondTol keyword). Out-of-plane angles are generated and printed if their values are below 10 degrees. Note, the procedure ignores dummy atoms. It is possible to force inclusion of particular atom pairs in the printed list of distances and hence to influence the generation of angles. For this the molecule-specific keyword GeomAddDistance can be used. For example

forces inclusion of distances between atoms in pairs 1—​3 and 4—​6 of the molecule mol irrespective of the lengths. Note, the numeration of atoms starts from 1 and includes also dummy atoms, although they are skipped in the procedure. The autogeneration of internal parameters may be switched off by defining explicit set of parameters for printing. For this, the MOLGEOMPRT command must be used as in the example below

If geometrical structure was refined by minimizing a combined least-squares functional then it is possible to print geometrical parameters with respective contributions from different LSQ functional parts into these parameters. For this the keyword CalcLsqFuncContrib must be used:

where mtd can be w1 or w2, which respectively correspond to the methods W1 [9] and W2 [10]. Together with contributions are printed values of parameters, their errors (standard deviations) from the latest refinement procedure and experimental errors. The latter are calculated according to the procedure described in [9] (UNEX uses a generalized form of Eq. 6 from the cited paper). The keyword LsqCalcExpErrExclFunc can be used to control which parts of the LSQ functional are excluded in calculation of experimental errors. The set of internal geometrical parameters is automatically generated by default. It is, however, possible to define explicitly a custom set using the MOLGEOMPRT command as described above. Note, the calculated values of contributions can depend to some extent on the composition of the complete set of internal parameters. This is the intrinsic property (a disadvantage) of the procedure.

This command prints restraining geometrical parameters for the molecule mol in comparison to respective model values. Note, the standard deviations are those from input and related to restraining values, not to the refined model values! In the end of the table some statistics are printed: maximal absolute deviation between model and restraining values MaxD, root-mean-square deviation RMSD and weighted (using input standard deviations of restraining values) root-mean-square deviation WRMSD, number of parameters used in calculation of statistics Nprm and index of parameter with the largest deviation ImaxD. The statistics are printed for all parameters and for groups of parameters of different types.

Z-matrices of molecules can be printed by calling

To print only parameters of Z-matrices use

There is a possibility for automatic generation and printing of Z-matrices, which can be done by using

Currently the only option for the type of generated Z-matrix is Type=pureCart. This will create a special case of Z-matrix containing only Cartesian coordinates as parameters. Refinement group numbres can be automatically assigned to each parameter by using the RefGrpStart keyword, for example to start numbering from 100 one can use:

Note, when calling this command the generated Z-matrix is only printed but not immediately used by UNEX. Use can utilize it as a template or directly copy-and-paste to UNEX input for further actual use.

The general command for printing Cartesian coordinates of atoms in molecules is

where format fmt can be unex (default) or mol (XYZ format [69]) and Dummy can accept boolean values true (print dummy atoms, default) or false (do not print dummy atoms).

All variants can print coordinates in Z-matrix (or input) orientation or in the system of principal axes of inertia tensor. This depends on the setting of the PrintXYZPAS keyword. Rotational constants are also printed when PAS is used. They are calculated for the current geometry in the RRPATM approximation: rigid rotor — point atomic masses.

In dynamic ED models potential energy functions are used. The command to print the respective data is

Note, the units of parameters are so that the potential energy is in kJ mol^-1 for the dynamic coordinate in radians.

ED scattering factors in the form of g-functions (scattering factor of atomic pair divided by atomic intensity) for all types of atomic pairs in the molecule can be printed using the command

This outputs data, produced by the respective EDSCATFAC command (see ED scattering factors). Note, in the case of models with mixtures of molecules the printed g-functions are calculated by dividing scattering factors by atomic scattering function of the respective molecule only. The bare scattering factors (not divided by atomic intensity) of atom pairs can be printed with the command

It is also possible to print atomic scattering functions for a specific molecule with the command

Different types of electron diffraction data can be printed by calling PRINT:EDDATA with the keyword Data, which accepts one or more arguments from the list below:

Note, model functions are (re)calculated before printing. In many cases several types of data are required for inspection/analysis and thus the particular arguments must be provided separated by the semicolon ; symbol, for example

The order of the arguments does not play any role. By default all available sets of ED data are printed. However, it is possible to print only particular set(s) of data, indicating respective identifiers in the PRINT command. The following command prints experimental molecular intensity only for the ed1 data set.

The levelled versions of the total intensity and background are curves obtained in the following manner. The total intensity function is approximated by a cubic spline (this is default, number of allowed inflection points is defined by the LvlItotNInflMax keyword) or a polynomial (if keyword LvlItotPolPow > 0 is defined). The original total intensity and background are divided by this smooth function and printed. The idea is to output curves which are easy to assess visually. It is important to use as less inflection points as possible (as low power for the polynomial as possible) so that oscillations on the original intensity and background are not influenced. Note, with this requirement splines and polynomials are not always the best approximations, so manual levelling may be required.

The other possibile modification of the total intensity and background are the so-called reduced variants iTotExpRed and iBgrRed. For the description of the calculation procedure for these functions see section ED background lines.

Together with the data for each set of curves some parameters and current settings are printed. Most of them are self-explanatory and correspond to keywords described in ED data sets. Some others are explained here:

Differences between ED experimental and model data can be printed in a special form suitable for producing Poincaré plots as

where dtype can be iTotDif or iMolDif for total and molecular intensities, respectively. Data for selected set(s) can also be printed just as in other modes above by indicating ED data set(s) explicitly, for example

There is a special command to print results of comparison of model and experimental ED molecular intensities:

This will print different types of R-factors (unweighted Rf und weighted wRd) in percent units for each set of ED data and total values for all data sets together. The definition of R-factors for sM(s) was given above in Least squares minimization chapter. In addition here are printed also R-factors, calculated for M(s) and s⁴I_mol(s) functions in analogous manner. Note, wRd values are meaningful only if standard deviations were defined (or calculated) for the respective sM(s). Also in this case wRd are equal for all types of molecular intensity, sM(s), M(s) and s⁴I_mol(s), by definition. Total wRd are meaningful only if standard deviations were defined or calculated for each data set. It is possible to print individual and total R-factors calculated only for a particular set of ED curves by providing identifiers of respective ED data sets, for example

For sM(s) in addition to R-factors are also printed Durbin–Watson statistics (see above), mean and maximal absolute values, mean and maximal absolute differences between model and experimental values.

Total ED intensities can be printed in format suitable for the Xcrystal program using the command:

Interatomic pairs with parameters relevant in the electron diffraction context, also known as ED terms, can be printed using the general command

where format can be unex, rsort or urdfplot. The default format is unex, which contains distances of r_a type, vibrational amplitudes and corrections, asymmetry constants for all pairs of atoms. Together with amplitudes corresponding errors are printed, which are the LS standard deviations (possibly multiplied by the factor PrintStdevFac) from the latest refinement. Note, it is possible that scale factors for amplitudes were refined. In this case their standard deviations are automatically recalculated into standard deviations of the respective amplitudes. Additionally, the so-called experimental errors are calculated in the same manner as for geometrical parameters when calling PRINT:MOLGEOMPRM with the CalcLsqFuncContrib keyword. In the last two columns refinement group numbers for amplitudes (or their scale factors) and for r_a distances are printed.

Using the format rsort it is possible to print ED terms sorted by the values of r_a distances in ascending order.

The other option Format=urdfplot prints ED terms in a format suitable for reading by the URDFPlot program. Note, the output in this format depends on the keywords EDRdfMultR, EDRdfTrmDifR and EDRdfTrmModAmpl. If EDRdfMultR=true then the RDFs are approximations of P(r) and the printed distances are of the r_g type. Otherwise, RDFs approximate the P(r)/r function and the printed distances are of the r_a type, respectively. Basic values for contributions of terms are calculated as products of respective atomic charges. They can be automatically modified depending on settings. For EDRdfMultR=false the contributions are additionally divided by the respective r_a distances. If EDRdfTrmDifR is active then the obtained values are multiplied by the respective multiplicity factors. In models of mixtures the contributions are also multiplied by respective mole fractions. In case of EDRdfTrmModAmpl=true the contributions are additionally divided by the respective amplitude values.

Parameters of molecules, which can be used in UNEX as GED standards, are printed by

Sector functions are printed by

With the optional DataType keyword it is possible to choose the particular type of data to be printed, the actual sector function (sfunc) or its regularization (sfreg). Otherwise both are printed.

Currently active (calculated, refined or introduced from the input file) response function for ED detector can be printed using the command