VIBROCC

The VIBROCC file lists the starting guesses for vibration amplitudes (in ångstrom) and site occupations. The minimum input is a vibration amplitude for each element in the POSCAR file. If the ELEMENT_MIX parameter is defined for an element in the PARAMETERS file, explicitly assigning vibration amplitudes and occupations to all sub-elements is recommended. See also this page for instructions on how to vary the occupation of a site during structure optimization.

Additionally, the VIBROCC file can contain a block defining offsets in vibration amplitudes, occupation, or position per element for specific atoms.

A VIBROCC file containing only some starting guesses for vibration amplitudes can be generated automatically using the VIBR_AMP_SCALE, T_EXPERIMENT and T_DEBYE parameters in the PARAMETERS file. See below for details.

Example

PARAMETERS file

ELEMENT_MIX M = Fe Ni
SITE_DEF O = surf top(2)
SITE_DEF M = surf top(2)

VIBROCC file

= Vibration Amplitudes
M_def = Fe 0.1, Ni 0.1
M_surf = Fe 0.125, Ni 0.12          !some comment
O_def = 0.19
O_surf = 0.18

= Occupations
M* = Fe 0.8, Ni 0.2
O_surf = 0.95

= Search offsets
POS 4 = Fe 0.0 0.0 0.01, Ni 0.0 0.0 -0.01     ! PFe_def
OCC 4 = Fe 0.01, Ni -0.01     ! PFe_def

The two main blocks in the VIBROCC files are Vibration Amplitudes and Occupations. Lines starting with = indicate the start of a block.

Vibration amplitudes and occupations

In each block, properties can be defined for each site type (left-hand side of =). The site types are labelled as El_sitename, where El is an element as found in the POSCAR file, and sitename is a site name defined in the PARAMETERS file under SITE_DEF. By default, an asterisk (*) is interpreted as a wildcard character, so O* will access both O_top and O_def.

If required, the left-hand parameters can also be interpreted fully as regular expressions (see also: python re syntax and python re HOWTO). This feature is turned off by default to avoid unintentional issues with e.g. full stops in site names (not recommended!), but can be turned on by inserting a line = regex on at any point in the VIBROCC file, and disabled later by the line = regex off. Note that if regular expressions is on, the asterisk * will not be a wildcard character any more (the equivalent would be .*)!

On the right-hand side of the = sign, you can either give only one value, or give multiple values for different elements. Here, the elements are either the ones found in the POSCAR file, or the ones defined in ELEMENT_MIX. If element names in the POSCAR file and in ELEMENT_MIX overlap, the assignment will nevertheless be made only for the chemical element, see element name collision. If only one value is given in the Vibration Amplitudes block, the vibration amplitudes for all elements in this site will be set to this value. If only one value is given in the Occupations block, this value will be set for the main site element (e.g., O for the O_top site), or for all main elements in a site affected by ELEMENT_MIX. The occupations for all other elements will be set to zero for this site.

Total occupation in a site can be smaller than one, which will be interpreted as the rest being vacancies. Defining an occupation greater than one will produce a warning and may halt execution; if execution proceeds, the occupation will be re-scaled to 1.

For simple systems, the Occupations block need not contain values for elements with 100% site occupation, and can even be left out entirely. The default value is 1.0 for the site’s main element and 0.0 for all other elements. If the site is affected by ELEMENT_MIX, the occupation will be evenly split between the sub-elements defined in ELEMENT_MIX. A simple example with 100% occupations and no ELEMENT_MIX might therefore look like this:

= Vibration Amplitudes
Fe_def = 0.10
Fe_surf = 0.18
O_def = 0.19
O_surf = 0.18

Search offsets

Apart from starting values for vibration amplitudes and occupations, the VIBROCC file can contain an additional block called Search offsets. This can be used to, for a specific atom, define position, vibration, or occupation offsets from the site’s values. This has two use cases:

  • If a parameter, e.g. the vibration amplitude, is varied independently for the different atoms sharing a site type, the search result will likely yield different values for these atoms. These values will be written to the OUT/VIBROCC file to initialize a potential continuation job with the exact results from the previous search, instead of an average.

  • If there are multiple elements sharing a site via ELEMENT_MIX, the positions of the different chemical species may be different depending on the element. This cannot be mapped in the POSCAR file or the reference calculation of TensErLEED, but can be mapped to the calculation via the Search offsets block by defining different values for different elements in the site.

Example:

= Search offsets
POS 4 = Fe 0.0 0.0 0.01, Ni 0.0 0.0 -0.01   ! for atom number 4, displace iron atoms by 0.01 A away from the bulk and Ni atoms 0.01 A towards the bulk.
OCC 4 = Fe 0.01, Ni -0.01                   ! for atom number four, there is 1% more iron and 1% less nickel than defined for the site type

The syntax for this block differs somewhat from the vibration amplitudes and occupations. On the left-hand side, each line is expected to contain:

  • A flag POS / VIB / OCC defining what type of parameter should be modified

  • An atom number (corresponding to the number in the POSCAR file)

On the right-hand side, the syntax is similar to the vibration amplitudes and displacements blocks. For vibration amplitudes or occupations, one value per element is expected, while for position offsets, three values per element are expected. The three values for geometry are cartesian \(x\), \(y\) and \(z\) offsets, in ångströms, where positive \(z\) means away from the surface.

OUT/VIBROCC

After executing a search, the VIBROCC file found in the OUT folder contains the vibration amplitudes and occupations of the best-fit structure found during the (last) search (i.e., the one with the smallest \(R\) factor). If atoms in the same site were allowed to vary independently, the vibrations and occupations written for each site will be the average, and values for the single atoms will be written as Search offsets.

When VIBROCC is automatically generated during Initialization, the resulting VIBROCC file is stored in the OUT folder.

At the end of each viperleed.calc execution, the file given as input for that run is renamed to VIBROCC_ori, while the (potentially) edited file is copied to the root directory (from OUT) as a new VIBROCC file. This ensures that further invocations of viperleed.calc will automatically use the output of previous executions as an input. You can manually call the bookkeeper utility after a specific viperleed.calc run if this behavior is not desirable. See the Bookkeeper page for more details.

Note

A non-halted execution (i.e., one where HALTING was set to a value larger than the default) that includes a structure optimization will overwrite an auto-generated OUT/VIBROCC file with the one found by the (last) optimization step. In this case, a copy of the auto-generated VIBROCC file can be found in SUPP (named VIBROCC_generated).

Changed in version 0.13.0: In earlier versions of viperleed.calc, the automatically created VIBROCC file would only appear in the root directory after Initialization, and only the VIBROCC file resulting from a structural optimization would be stored in OUT. This file used to be named VIBROCC_OUT.

Automatic generation of VIBROCC

ViPErLEED can automatically generate a VIBROCC file containing starting guesses for vibration amplitudes. To do this, the experiment temperature \(T\) (T_EXPERIMENT) and the sample Debye temperature \(\Theta_\mathrm{D}\) (T_DEBYE) must be specified in PARAMETERS. Additionally, VIBR_AMP_SCALE must be set if you are using non-default sites (which is generally recommended).

Given these parameters and the atomic masses \(m\), the atomic vibration amplitudes can be estimated as [26, 27]

\[\langle u^2 \rangle _{T} \approx \frac{9 \hbar^2}{4 m k_\mathrm{B} \Theta_\mathrm{D}} \left[1+ 4\left(\frac{T}{\Theta_\mathrm{D}}\right)^2 \int_{0}^{\frac{\Theta_\mathrm{D}}{T}} \frac{x}{e^x - 1} dx\right].\]

Here \(\hbar\) and \(k_\mathrm{B}\) are the reduced Planck’s and Boltzmann’s constants, respectively.

The integral can not be evaluated analytically, but a good approximation is given by a combination of its low- and high-temperature limits

\[\langle u^2 \rangle _{T} \approx \sqrt{ (\langle u^2 \rangle _{T=0})^2 + (\langle u^2 \rangle _{T \rightarrow \infty})^2 }.\]

Evaluating these limits,

\[ \begin{align}\begin{aligned}\langle u^2 \rangle _{T=0} = \frac{9 \hbar^2}{4 m k_\mathrm{B} \Theta_\mathrm{D}},\\\langle u^2 \rangle _{T \rightarrow \infty} = \frac{9 \hbar^2 T}{m k_\mathrm{B} \Theta_\mathrm{D}^2},\end{aligned}\end{align} \]

gives

\[\langle u^2 \rangle _{T} \approx \frac{9 \hbar^2}{4 m k_\mathrm{B} \Theta_\mathrm{D}} \sqrt{1+16\left(\frac{T}{\Theta_\mathrm{D}}\right)^2}.\]