periodica.py

SOURCE: periodica.py

Periodica is a program / module to process crystal structures (and theoretically atoms too). It uses the POSCAR format of VASP (see here http://cms.mpi.univie.ac.at/vasp/vasp/POSCAR_file.html), but is able to read/write other formats as well. It also has command-line options. It is object oriented so can be implemented in other python programs as well with the “structure” class (examples below).

Instantiation

If you’re using python, then you can instantiate the structure class with either the POSCAR contents or the filename. Any of the following will work:

structure(open('POSCAR').read())
structure(open('CONTCAR').readlines())
structure('POSCAR_01')

If you’re using the command-line, then you can pipe the file in, or identify it by name, or leave it out and use defaults (it tries CONTCAR first then POSCAR):

periodica.py CONTCAR_01

Frequent methods

Here are some of the more common methods that you might use in periodica. The parentheses identify the command used to call it from the command-line, UNIX-style. For example, to draw a supercell with shifted origin using jmol, the command-line argument might be:

periodica.py supa='2 0 0 0 2 0 0 1 2' -jmol shift='0.5 -0.3 0.5'

Here are some important methods. Full usage is detailed below, but this should give you an idea of what you can do.

  • pposcar (CL: None) This is the default if no other command is given in the command line. st.pposcar() prints to stdout; a string argument prints to that file; an argument ‘t’ or 1 or True returns the POSCAR as a string. There are also ptart, pstut, pabinit, ppwscf, pdmftlab methods.

  • dirtocar (CL: dirtocar) Toggles direct or cartesian coordinates

  • supa (CL: supa=’1 0 0 0 2 0 0 0 1’) Supersizes the cell with a 3x3 matrix; coordinates given are direct. There is also a method to get the smallest supercell that contains a given k vector.

  • allincell (CL: allincell) Shifts all atoms by lattice vectors to ensure they are within the unit cell. There is also an outofcell method.

  • xyz (CL: jmol) Displays the structure using jmol. There is an argument “force” (commmand-line -force) that adds forces from the OUTCAR.

  • dist (CL: dist) Prints out distances between all two atoms, up to a tolerance, with a particular verbosity (see docstring).

  • axial_strain (CL: strain) Strains the unit cell

  • shift_origin (CL: shift=’a b c’) Shifts the origin by a constant given in direct coordinates. There is also a rot method for rotation.

  • shift_atom (CL: shiftatom / shiftatomc) Shifts a particular atom

Known bugs / issues

  • The distance-finding method has a counterintutive definition of distances, where the output “C1—O2” means “the distance going from O2 to C1”.

  • Some old versions have a supa method that doesn’t automatically look in the (0,0,0) translation for atoms.

  • Some versions are not compatible with VASP 5 output, where the atom species are printed in their own line

  • Periodica’s distance function can be computationally intensive for large cells

Docstrings from boomerang.py