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.

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, i.e. the 5^th atom in the POSCAR/POTCAR has the label 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]
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
layers@create byatom|bytype nr1 [nr2] [...]	create an atomic layer defined by specific atom numbers (byatom) or atomic types (bytype)
layers@delete	delete a definition of an existing atomic layer
layers@join	join (=concatenate) 2 or more atomic layers
layers@look x|y|z [nr]
layers@ls	list atomic layers
layers@measure spacing|distance|angle specification
layers@order
layers@shift
list	list the POSCAR/CONTCAR file
load file	load the file (usually POSCAR/CONTCAR) to buffer
loud
ls	list the POSCAR/CONTCAR file
measure
open
origin
pbc	apply periodic boundary conditions (PBS) - all atoms with coordinates sticking out of the supercell will be moved inside; use with caution
prefix number	change the prefix factor (2nd line in POSCAR) to a specified number
pretty
quiet	enter quiet mode - reduce UPU messages to minimum
quit	exit
redo
replicate
rotate
save [file]	save the current state of the buffer (structure) to a file
scale
script
seldyn
select
selection
sense
strain
undo
unselect
update

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.:

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

Note: Currently, UPU may work smoothly on local machines and on TEKLA (but not on TEKLA2).