UPU

go back to Main Page, Computational Resources, Chemistry & More, Computational Codes, VASP

DESCRIPTION

UPU = Universal POSCAR Utilities

UPU is a powerful command-line tool for processing POSCAR/CONTCAR files under Linux/UNIX.

It enables viewing, modifying and extracting information of those structure files interactively or in a batch (awk-like scripting) mode.

As the program is a rather private project of the only developer Dr. M. Jahnátek (Univ.Vienna [1]), it is not documented elsewhere.

SYNTAX

UPU is programmed in C language and uses a C-like syntax.

Script mode:

upu '{command1;command2}' POSCAR|CONTCAR

Interactive mode:

upu POSCAR|CONTCAR

(or just "upu" command). You are redirected to the UPU sub-shell. The output of inserted commands is directly listed into the UPU shell. Press <ESC><ESC> or type quit command to return to BASH shell.

Note: C-like syntax also means that UPU starts to count atoms and atomic layers from 0, e.g. the 5^th atom in the POSCAR/POTCAR has the label (ID) 4. Take care of avoiding errors based on wrong numbering.

USAGE

Example #1 (level 1)

upu '{cartesian;ls;save;export xsf}' /path/to/CONTCAR

The command proceeds the following steps: reads a CONTCAR file, switches easily from the default direct coordinates to Cartesian, prints this half-edited version of CONTCAR to the the stdout, saves it the modification (output file "CONTCAR"), exports and saves the supercell to the XCrysDen format (output file "CONTCAR.xsf") and quits to BASH shell.

Example #2 (level 2)

upu '{cartesian ;\
      measure distance a 0 a 1 ;\
      measure angle a 0 a 1 a 2 ;\
      measure dihedral a 0 a 1 a 2 a 3
      }' /path/to/CONTCAR

The command reads in a stucture-*CAR file, and measures the distance between atoms # 1 and 2, the bond angle between the atoms # 1-2-3 and the dihedral angle on the atoms # 1-2-3-4.

Each measurement has a one-line numerical output, thus it is easy to be parsed. So if the output of the upu command is redirected into a file ("upu '{commands}' CONTCAR > data.dat"), you can easily parse the variable in a BASH-script using e.g.

tail -3 data.dat > temp.dat
for i in `seq 1 3` ; do
 var[$i]=`awk -v line=$i '(NR==line){print $1}' temp.dat`
done

LIST OF COMMANDS

Listed alphabetically:

aassoct	attempt to specify atom types automatically by reading OUTCAR file in the current directory (no parameters needed)
assoct element1 [element2] [...]	associate the previously unspecified atom types with the user input (e.g. "assoct Pt N H")
bye	exit
cartesian	switch atom coordinates being shown in Cartesian format
cell	print cell parameters
cmd
commandline
cmd
curl
direct	switch atom coordinates being shown in direct (=fractional) format
deassoct
exchange
exit	exit
export XSF|AXSFF|XYZ|UNIXYZ|XYZ_WTA|UNIXYZ_WTA	convert and save the structure in a specified file format: XSF (XCrysDen file format), AXSFF (animation for XCrysDen - step-by-step creation), XYZ (Open Babel compatible), UNIXYZ (UniChem compat.),
extract
fractional	switch atom coordinates being shown in direct (=fractional) format
identify
kpoints
kpoints@ls
kpoints@save
kpoints@set
la	list atoms
label text	change the label of the structure file (1st line in POSCAR) to a specified text
layers@alook x|y|z	automatically search for atomic layers along the given axis
layers@buckling nr	perform comprehensive statistics on buckling of the given layer
layers@create byatom|bytype nr1 [nr2] [...]	create an atomic layer defined by specific atom numbers (byatom) or atomic types (bytype)
layers@delete [hard] nr1 [nr2] [...]	delete a definition of an existing atomic layer(s); the "hard" switch causes removing the atoms from the unit cell
layers@join	join (=concatenate) 2 or more atomic layers
layers@look x|y|z nr	find atomic layers along the given axis by splitting the corresponding lattice vector length into "nr" slides
layers@ls	list atomic layers
layers@measure spacing|distance|angle spec
layers@order x|y|z	order atom layers along the given axis; needed before starting measurements with layers
layers@shift nr by x y z	shift (translate) all atoms of a given layers in the direction specified by vector x y z
list	list the POSCAR/CONTCAR file
load file	open (=load) the file (usually POSCAR/CONTCAR) to buffer
loud	enter loud mode - UPU messages are not restricted
ls	list the POSCAR/CONTCAR file
measure distance|angle|dihedral a nr1 a nr2 [a nr3] [a nr4] [short]	measuring tool: explore distances (distance), angles (angle) or dihedral angles (dihedral) between specified atoms.
open	open (=load) the file (usually POSCAR/CONTCAR) to buffer
origin atomnr	specify an atom to be a new origin of the coordinate system (i.e. shift all atoms' coordinates by the translation vector x,y,z of atom atomnr)
pbc	apply periodic boundary conditions (PBC) - all atoms sticking out of the unit cell will be moved inside; use with caution
prefix number	change the prefix factor (2nd line in POSCAR) to a specified number
pretty	adjust vector coordinates to a "pretty" format with the accuracy of 1E-9
quiet	enter quiet mode - reduce UPU messages to minimum
quit	exit
redo	redo the last reverted change by "undo"
replicate x y z	replicate the unit cell x-, y- and z-times in the corresponding directions
rotate
save [file]	save the current state of the buffer (structure) to a file
scale A|B|C|VOLUME|LATTICE factor	multiply lattice vector(s) or cell volume by a given factor>
script
seldyn on|off|fix|free
select atom|type nr1 [nr2] [...]	activate selection on atom(s) of a specified atom number or type
selection
sense	check orthogonality of the unit cell basis vectors
strain
undo	undo the last change
unselect atom|type nr1 [nr2] [...]	deactivate selection on atom(s) of a specified atom number or type
update	perform UPU software update (eventualy downloads the latest version via internet with curl command); UPU possibly restarts

Note:

All UPU commands are non-destructive to the original structure file unless you use the "save" (overwrites the open file or creates a new one) or "export" (always creates a new file) command.

Remarks on the measure command:

1. Specially, "measure distance" without parameters prints the full distance matrix.

2. Use the optional "short" keyword if a you measure malformed quatities caused by atoms' shift due to PBC conditions (when atoms "run out of the cell and appear on the other side"). Example: "measure angle a 0 a 1 a 7 short" is the smallest possible angle between atoms # 1-2-8.

3. Alternatively, instead of "a nr" arguments ("a" stands for "atom"), you may specify measurements using atom's image defined as "i nr x y z" ("i" stands for "image of atom", "nr" is the node atom, "x y z" is the imaging (translation) direction along the lattice vectors, ). Example: "measure angle a 3 i 3 0 0 -1 a 4" uses atom #4, an image of an atom # 4 (in a the first neighbouring cell lying below in z-direction) and atom # 5 - useful for measuring tilting angles on surfaces etc..

INSTALLATION

Although UPU is a freeware, you will not find it easily in internet. The compressed packages are located at the author's homepage (binary (5.9MB)).

The preferred way of installation is the following:

wget -nv http://homepage.univie.ac.at/michal.jahnatek/upu/upu-1.4.0-linux-bundle.tar.bz2
mkdir ~/bin/upu ; tar -C ~/bin/upu -xjf upu-1.4.0-linux-bundle.tar.bz2

Do not forget to update your $PATH shell variable, e.g. by running the command:

printf '\nexport PATH=$PATH:~/bin/upu\n' >> ~/.bashrc

Note: Currently, UPU seems to work smoothly on local machines (Ubuntu) and on TEKLA1 (Debian).

In order to install on TEKLA2 (SUSE), in addition you have to substitute one of the shared libraries as follows:

wget -nv http://homepage.univie.ac.at/david.karhanek/shared/tekla2-libstdc.bz2
tar -C ~/bin/upu/lib64 -xjf tekla2-libstdc.bz2
cd ~/bin/upu/lib64/ ; rm -f libstdc++.so.6 ; ln -s libstdc++.so.6.0.11 libstdc++.so.6

--Dkarhanek 13:02, 1 October 2010 (CEST)