Editing UPU

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

== DESCRIPTION ==
<p align="center" style="width:100%">
{| border="4" 
 |- 
 | &nbsp; &nbsp; '''UPU''' = '''U'''niversal '''P'''OSCAR '''U'''tilities &nbsp; &nbsp;
 |}
</p>

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 (<TT>awk</TT>-like scripting) mode.

As the program is a rather private project of the only developer Dr. M. Jahnátek (Univ.Vienna [http://www.cms.tuwien.ac.at/cms/person/63/]), it is not documented elsewhere.

== SYNTAX ==

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

Script mode:
 upu '{command1;command2}' POSCAR&#124;CONTCAR

Interactive mode:
 upu POSCAR&#124;CONTCAR
(or just "<TT>upu</TT>" command). You are redirected to the UPU sub-shell. The output of inserted commands is directly listed into the UPU shell. Press &#60;ESC&#62;&#60;ESC&#62; or type <TT>quit</TT> 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<sup>th</sup> 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 <TT>stdout</TT>, 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 ''measure''ment has a one-line numerical output, thus it is easy to be parsed. So if the output of the <TT>upu</TT> command is redirected into a file ("<TT>upu '{commands}' CONTCAR > data.dat</TT>"), 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:

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


'''Note:''' 

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

'''Remarks on the <TT>measure</TT> command:'''

1. Specially, "<TT>measure distance</TT>" without parameters prints the full distance matrix.

2. Use the optional "<TT>short</TT>" 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: "<TT>measure angle a 0 a 1 a 7 short</TT>" is the smallest possible angle between atoms # 1-2-8.

3. Alternatively, instead of "<TT>a ''nr''</TT>" arguments ("a" stands for "atom"), you may specify measurements using atom's image defined as "<TT>i ''nr x y z''</TT>"  ("<TT>i</TT>" stands for "image of atom", "<TT>nr</TT>" is the node atom, "<TT>x y z</TT>" is the imaging (translation) direction along the lattice vectors, ).  
Example: "<TT>measure angle a 3 i 3 0 0 -1 a 4</TT>" 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 ([http://homepage.univie.ac.at/michal.jahnatek/upu/upu-1.4.0-linux-bundle.tar.bz2 binary (5.9MB)]).

The preferred way of installation is the following:
 wget 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 <TT>$PATH</TT> shell variable, e.g. by running the command:
 printf '\nexport PATH=$PATH:~/bin/upu\n' >> ~/.bashrc ; source ~/.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 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

--[[User:10.0.7.17|10.0.7.17]] 13:54, 6 June 2011 (CEST)