DISPLACEMENTS

The DISPLACEMENTS file defines the types and ranges of of geometry, vibration amplitudes, and element concentrations that are varied in the search, error calculation and superpos calculation. In other words, the DISPLACEMENTS file defines the parameter space that is sampled in tensor-LEED based structure optimizations.

Note

This page gives a top level overview of the DISPLACEMENTS file. For details on the syntax of the individual blocks, see the relevant links.

Allowed parameters are split into three main blocks: Geometry, Vibrations, and Occupations. The blocks are delimited by lines starting with an equals sign “=”, as in the following example

= GEO_DELTA
O 1 z = -0.05 0.05 0.005      ! Oxygen atom 1 (and symmetry-equivalent atoms) will be displaced in z direction over the range [-0.05, 0.05] with step 0.005
Ir 2-11 z = -0.05 0.05 0.01   ! Iridium atoms 2-11 (and symmetry-equivalent atoms) will be displaced in z direction over the range [-0.05, 0.05] with step 0.01
O L(2-4) z = -0.05 0.05 0.01  ! Oxygen atoms in layers 2-4 will be displaced in z direction over the range [-0.05, 0.05] with step 0.01

= VIB_DELTA
O 1 = -0.05 0.05 0.02         ! Vibration amplitude of oxygen atom 1 (and symmetry-equivalent atoms) will be varied over the range [-0.05, 0.05] with step 0.02
Ir_top = -0.05 0.05 0.01      ! Vibration amplitude of Iridium atoms in Ir_top sites will be varied over the range [-0.05, 0.05] with step 0.01

= OCC_DELTA
O 1 = O 0.8 1.0 0.05          ! Concentration of oxygen atom 1 (and symmetry-equivalent atoms) will be varied from 80% to 100% with 5% steps (rest: vacancies)

In each of the lines in the blocks, the left side of the = sign defines which atoms are being assigned displacements, while the right side defines the range of displacements to apply. Generally, atoms can be addressed by POSCAR element, chemical element, or site type. If there is an element name collision, the element will be interpreted as the POSCAR element, so the assignment will be made for all elements in ELEMENT_MIX. Supplying a list of atom numbers (N in POSCAR, or by layer number using L(x) for layer x) to further limit which atoms are being addressed is optional. If no numbers are given, the displacements on the right are applied to all atoms of the given element/site.

Any displacement applied to one atom will also be applied to all symmetry-equivalent atoms (see Linking in POSCAR), such that the symmetry is preserved during the search (e.g. in-plane geometric displacements will be mirrored for atoms linked by a mirror symmetry plane). If multiple assignments are made for the same atom, the assignments will be ignored if they are consistent, but the user will be warned and the program may stop if there is a contradiction. For example, if some of the iridium atoms 2–11 in the code above were linked by a mirror plane, assigning a displacement in \(z\) direction to all of them would be accepted, but assigning the very same in-plane displacement (not parallel to the mirror plane) to all of them would lead to a contradiction, as this would break the symmetry. In that case, it would be preferable to assign the displacement explicitly to only one of the symmetry-equivalent atoms.

The syntax of the three blocks differs slightly, and is explained in detail here:

• Geometric displacements

• Vibration amplitudes

• Chemical substitution

Note

In the TensErLEED backend, geometric displacements for any atom can only be applied along one direction (e.g., \(z\), \(x\), \(y\), along arcs, etc.) at a time. The DISPLACEMENTS file can contain multiple search blocks that are executed in sequence as described below. To optimize positions in multiple directions, multiple subsequent search blocks are necessary.

Note

Indentation in the DISPLACEMENTS file is allowed, but does not affect function.

Note

See the Domain calculations page for information on how to format the DISPLACEMENTS file when optimizing multiple structures simultaneously.

Advanced functionality

CONSTRAIN block

If some displacements should be constrained or linked in ways that go beyond simple symmetry conservation, arbitrary displacements can be linked by using CONSTRAIN blocks.

= VIB_DELTA
Ir_top = -0.05 0.05 0.02     ! see above; for example below

= CONSTRAIN
geo O_top, Ir_top = linked   ! keep geometric displacement index the same for O_top and Ir_top atoms. Requires the displacement ranges to have the same number of steps.
vib Ir_def = linked          ! keep vibration displacement index the same for all Ir_def atoms

OFFSETS

It is possible to apply an offset to the displacement range of an atom, i.e., to shift the center of the displacement range away from the position of the reference calculation. The OFFSETS block, if used, has to be placed at the top of the DISPLACEMENTS file. Details on the syntax of the OFFSETS block are given in the respective documentation page.

If multiple search blocks or search loops are used, the offset will be applied only to the first search. Subsequent searches will be centered around the final position from previous searches.

Search Blocks

If you want to optimize multiple parameters not simultaneously, but end-to-end (necessary e.g. for optimization of atomic positions), you can use multiple blocks in the DISPLACEMENTS file to express this. After finishing one set of delta calculations and search, the program will then loop back to execute delta calculations and search again, starting from the optimized results of the previous search.

For example, the following DISPLACEMENTS file would first optimize \(z\) position and vibration amplitudes simultaneously for the given set of atoms, then run another search from the optimized \(z\) and vibration amplitudes, this time optimizing the \(x\) coordinate:

== SEARCH z

  = GEO_DELTA
  Ir L(1-6) z = -0.05 0.05 0.01

  = VIB_DELTA
  Ir = -0.005 0.005 0.0005

== SEARCH x

  = GEO_DELTA
  Ir L(1-6) xy[1 0] = -0.03 0.03 0.01

The successive search blocks are each introduced by a line starting with == SEARCH. Any text after the == SEARCH tag in the same line will be treated as a ‘name’ for the block (in the above example z and x). The name will be referenced in the log files, but does not have any influence on the behavior of the program.

Note

See MAX_TL_DISPLACEMENT for options to automatically insert reference calculations between searches if displacements become unreasonably large.

In-plane optimization shorthand

If you want to run one search to optimize positions in one in-plane direction (e.g., x), then another search for the other direction, you can either write out two search blocks, or abbreviate by entering just xy or ab as the direction, without the brackets to indicate a specific direction. This will effectively expand the block into two subsequent blocks, using the [1 0] direction in the first and the [0 1] direction in the second one. For example

== SEARCH xy

  = GEO_DELTA
  Ir L(1-6) xy = -0.03 0.03 0.01

  = VIB_DELTA
  Ir = -0.005 0.005 0.0005

is equivalent to

== SEARCH xy[1 0]

  = GEO_DELTA
  Ir L(1-6) xy[1 0] = -0.03 0.03 0.01

  = VIB_DELTA
  Ir = -0.005 0.005 0.0005

== SEARCH xy[0 1]

  = GEO_DELTA
  Ir L(1-6) xy[0 1] = -0.03 0.03 0.01

  = VIB_DELTA
  Ir = -0.005 0.005 0.0005

Looping searches

It is possible to have a set of search blocks running in a loop using the tags <loop> and </loop>. Note that these flags are expected to always be directly before a == SEARCH statement, or before the end of the file. Loops will end when their latest iteration does not yield a better \(R\) factor than the previous iteration (note that this means each looped block will be executed at least twice). For example, to optimize the \(z\) coordinate, then search \(x\) based on the optimized \(z\), and then loop back to searching \(z\) with the optimized \(x\), the example above could be modified like this:

<loop>
== SEARCH z

  = GEO_DELTA
  Ir L(1-6) z = -0.05 0.05 0.01

  = VIB_DELTA
  Ir = -0.005 0.005 0.0005

== SEARCH x

  = GEO_DELTA
  Ir L(1-6) xy[1 0] = -0.03 0.03 0.01

</loop>

You can also nest loops; for example, to optimize \(z\), then loop in-plane optimization to get optimal \(x\) and \(y\) for that \(z\), then start again with \(z\), you could do:

<loop>

== SEARCH z

  = GEO_DELTA
  Ir L(1-6) z = -0.05 0.05 0.01

  = VIB_DELTA
  Ir = -0.005 0.005 0.0005

<loop>

! This block will automatically be split into separate blocks for optimizing x and y
== SEARCH xy

  = GEO_DELTA
  Ir L(1-6) xy = -0.03 0.03 0.01

</loop>
</loop>

Note

If looped searches are interrupted by MAX_TL_DISPLACEMENT for a reference calculation and then continued, the previous \(R\) factor to compare to will be discarded, as very different values may be obtained. Each looped block will therefore again be evaluated at least twice.