POSCAR utilities
ViPErLEED comes with a set of utilities for easy manipulation of POSCAR files. These utilities can be helpful for creating and modifying input structures for ViPErLEED calculations.
All POSCAR utilities support the following options:
-h, --help: show a help message with the available options-v, --verbose: increase output verbosity
Hint
Most ViPErLEED POSCAR utilities read from stdin and write to
stdout. This means that you can easily use them in a pipeline,
e.g.,
$ cat POSCAR | viperleed poscar delete_above C | viperleed poscar enforce_symmetry >POSCAR_OUT
Tip
If you find these utilities useful, consider adding an alias to your
.bashrc so you don’t have to type viperleed poscar every time.
attach_bulk
Interactive script that takes a slab POSCAR and adds a bulk POSCAR on the bottom, expanding the the unit cell in the \(\mathbf{c}\) direction accordingly.
Usage
$ viperleed poscar attach_bulk
Additional Options
None.
delete_above
Deletes all atoms in the POSCAR file above the specified fraction of the \(\mathbf{c}\) vector.
With the --verbose option, the utility prints the number of atoms deleted.
This can also be useful to quickly check the number of atoms above a certain
height.
Usage
$ viperleed poscar delete_above C <POSCAR_IN >POSCAR_OUT
Additional Options
c(required): the fraction (floating point number) of \(\mathbf{c}\) above which to delete atoms.
delete_below
Same as delete_above, but deletes all atoms below the specified fraction of the \(\mathbf{c}\) vector.
Usage
$ viperleed poscar delete_below C <POSCAR_IN >POSCAR_OUT
Options
c(required): the fraction (floating point number) of \(\mathbf{c}\) below which to delete atoms.
delete_between
Same as delete_above and delete_below, but deletes all atoms between the specified fractions of the \(\mathbf{c}\) vector.
Usage
$ viperleed poscar delete_between C1 C2 <POSCAR_IN >POSCAR_OUT
Additional Options
c1(required): delete atoms with \(c_1 < c < c_2\)c2(required): see above
enforce_symmetry
Finds the planegroup of the POSCAR file and enforces it by moving atoms to symmetric positions.
Symmetry detection works the same as the find_symmetry utility but here a symmetrized POSCAR file is returned.
Usage
$ viperleed poscar enforce_symmetry <POSCAR_IN >POSCAR_OUT
Additional Options
-e, --symmetry-eps: Epsilon for in-plane symmetry detection in Å. Behaves like SYMMETRY_EPS in the PARAMETERS file. Default: 0.1Å--symmetry-eps-z: Epsilon for out-of-plane symmetry detection in Å. Behaves like the second argument of SYMMETRY_EPS in the PARAMETERS file. If not provided, the value of--symmetry-epsis used.--planegroup: Planegroup to enforce. Default: detected automatically from the slab. Use this option to override the automatic detection and manually lower the symmetry.
Example
$ viperleed poscar enforce_symmetry <POSCAR_IN >POSCAR_OUT --symmetry-eps 0.01
find_symmetry
Finds the planegroup of the POSCAR file and prints it to stdout.
This utility uses the same algorithm for symmetry detection as is used
in ViPErLEED calculations.
Usage
$ viperleed poscar find_symmetry <POSCAR_IN
Additional Options
-e, --symmetry-eps: Epsilon for in-plane symmetry detection in Å. Behaves like SYMMETRY_EPS in the PARAMETERS file. Default: 0.1Å--symmetry-eps-z: Epsilon for out-of-plane symmetry detection in Å. . Behaves like the second argument of SYMMETRY_EPS in the PARAMETERS file. If not provided, the value of--symmetry-epsis used.
get_bulk_repeat
Interactive script that reads a POSCAR file, asks at what c value the bulk
starts, then automatically reduces the size of the POSCAR to non-redundant
bulk layers only, and outputs the appropriate N_BULK_LAYERS and
BULK_REPEAT values.
Additionally, the files POSCAR_bulk containing the bulk unit-cell and
a file POSCAR_min containing the minimal surface slab will be written.
Usage
$ viperleed poscar get_bulk_repeat
Additional Options
None.
merge
Merges two or more POSCAR files into one.
All files must have the same unit cell dimensions (within a tolerance defined
by the --eps option).
The resultant POSCAR file will contain all atoms from all input files. This can be used to stitch together superstructures and a bulk cell, for example.
The utility raises an error if any two atoms are closer than
--eps-collision. This can also be used to check if atoms from different
slabs (with the same unit cell dimensions) are in the same positions.
Usage
$ viperleed poscar merge POSCAR1 POSCAR2 ... >POSCAR_OUT
Additional Options
--eps-cell: tolerance for checking that the unit cell dimensions of the input files are the same (default: 1e-1)--eps-collision: tolerance for checking that no two atoms are closer than this distance (default: 0.1)
modify_vacuum
Modifies the vacuum spacing of a POSCAR file.
While most DFT codes use periodic boundary conditions along the z direction, in LEED calculations the symmetry has to be broken in order to simulate a surface. This utility allows to modify the vacuum spacing of a POSCAR file by adding or removing vacuum around the slab.
Usage
$ viperleed poscar modify_vacuum 10 <POSCAR_IN >POSCAR_OUT # add 10 Å of vacuum
Additional Options
vacuum(required): Add or remove this amount of vacuum in Å. If the flag--absoluteis set, the total vacuum spacing (measured from topmost to bottommost atom) will be set to this value.--absolute: see above.
project_c_to_z
Projects the \(\mathbf{c}\) vector of the POSCAR file onto the \(z\) axis. Note this does not alter atomic coordinates, only the orientation of the lattice vectors. The bulk-stacking direction is assumed to be along the \(\mathbf{z}\) vector. See also the page on used conventions.
Usage
$ viperleed poscar project_c_to_z <POSCAR_IN >POSCAR_OUT
Additional Options
None.
reorder_elements
Reorders the element blocks in the POSCAR file.
By default, the element blocks are reordered by ascending atomic number. Use options listed below to change the order.
Usage
$ viperleed poscar reorder_elements <POSCAR_IN >POSCAR_OUT # ascending atomic number
$ viperleed poscar reorder_elements --custom=O,Fe <POSCAR_IN >POSCAR_OUT # custom order
Additional Options
--alphabetical: sort elements by alphabetical order of the element symbols--descending: sort elements by descending atomic number--custom: sort elements by a custom order (comma-separated list of element symbols)
rescale_cell
Rescales the unit cell dimensions of the POSCAR file by the specified factor. Irrespective of how many values are give, this utility will directly alter the unit cell basis vectors in the POSCAR file, not the scaling factor (line 2).
Usage
$ viperleed poscar rescale_cell 1.01 <POSCAR_IN >POSCAR_OUT # stretch isotropically by 1%
$ viperleed poscar rescale_cell 1.01 1.02 0.99 <POSCAR_IN >POSCAR_OUT # stretch anisotropically
Additional Options
scaling: (required) One or three scaling factors for the unit cell. If three values are given, the scaling factors are applied to the \(\mathbf{a}\), \(\mathbf{b}\), and \(\mathbf{c}\) vectors, respectively. If only one value is given, an isotropic scaling is applied.
sort_by_z
Sorts the atoms in the file by their z-coordinate within each element block. To reorder the element blocks themselves, use reorder_elements.
Usage
$ viperleed poscar sort_by_z <POSCAR_IN >POSCAR_OUT
Additional Options
--reversed: sort elements bottom to top (default: top to bottom)
strip_comments
Strips all comments from the POSCAR file (e.g. SITE_DEF information added by ViPErLEED). This can also be used to strip ion velocities from a VASP POSCAR file.
Usage
$ viperleed poscar strip_comments <POSCAR_IN >POSCAR_OUT
Additional Options
None
vasp_relax
Formats the POSCAR file for use with VASP.
It can often be useful to “pre-relax” a surface structure with DFT calculations before performing a LEED-I(V) analysis. This utilities facilitates this by formatting the POSCAR file for relaxation with VASP. The vasp_relax utility adds the following information to the POSCAR file:
the tag
Selective dynamics, which indicates to VASP that selected ion positions are allowed to movethree boolean flags (T, F) for each atom indicating whether the atom is allowed to move along the \(\mathbf{a}\), \(\mathbf{b}\), and \(\mathbf{c}\) unit-cell vectors, respectively
In general, it can be useful to optimize the positions of the topmost layers
of atoms, while keeping the positions of the atoms in the bulk fixed.
The above_c value should be chosen such that bulk atoms are not allowed
to move to prevent the bulk lattice parameters from changing.
Usage
$ viperleed poscar vasp_relax 0.20 <POSCAR_IN >POSCAR_OUT
$ viperleed poscar vasp_relax 0.35 --all_directions <POSCAR_IN >POSCAR_OUT
Additional Options
above_c: (required) the fraction of the \(\mathbf{c}\) vector above which to allow atoms to move--all_directions: allow all atoms to move along all three unit cell vectors (default: only allow movement along \(\mathbf{c}\))