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

class periodica.structure(poscar)

A general class to store, manipulate, and print a lattice.

addneighbor(bond, cut, trans=1)

add neighbors within a specific range to a given atom

allincell(tol=10)

Translate basis atoms such that they all exist within unit cell.

auto_label(ddir='./')

Label the atoms with names. Take these from Poscar, or from POTCAR or OUTCAR. If none of these exist, a default sp1, sp2, sp3,... will be given.

axial_strain(inp)

Strains the unit cell. user must supply x,y,z strains as the string ‘s1 s2 s3’

bonds(max, bond='all')

find all bonds which are less than length max. bond is of format sp1-sp2 (ie. Co-O) or all.

build_ws_from_translations(ws, vec, at, atc, tto, tfrom=-1)

An incremental tool of constructing ws cell translations

cellcenter()

return the center of mass of the unit cell

cellinfo()

Caclulates the cell volume and the vector lengths and anglges.

closestto(inp=0)

shift all atoms by translation vectors within a shell such that they are closest to atom inp

clustercenter()

center of the cluster of the unit cell

combine(other)

Combine two structures.

completecellxyz(inp='', tol=1e-06)

Complete the unit cell for viewing

(ie. add a translated atom for each component of any atom with a zero direct coordinate).

The input determines which directions one completes in. It should be understood that one is

left with a cluster and NOT a unit cell.

dirtocar()

Changes the print format from direct to cartesian or vice versa.

displace_mode_q(qvec, delta, atpol=None, atpol_vec=None, renormalize_delta=False, use_real=True)

This method will use the q basis, possibly under some unitary transformation, to displace the atoms by some amplitude. qvec - This is the qvector. delta - amplitude of distortion. atpol - atom/polarization 2-tuple ie. (0,’p_x’) atpol_vec - This is a vector, giving a linear combination of get_basis_q. renormalize_delta - This make delta the largest displacment within the mode, as opposed to mode amplitude. use_real - use 0.5*(qvec+qvec_bar). Else, use 0.5*(qvec-qvec_bar).

dist(verb=0, cut=2.5, transx=2, transy=2, transz=2, output='print')

Prints out the distances between atoms. There is four levels of verbosity (ie. verb=0-3). Cut specifies the maximum bond length displayed. The trans paramters should not need to be changed. These set how many translations are taken to look for neighboring atoms.

get_basis_q(qvec, unitary_trans=None)

For a given q-vector create each atom/polarization displacement vector transforming like it. It is returned as a OrderedDict called basis. a=get_basis_q((1/2,0,0)) Each entry, such as a[(0,’p_x’)], corresponds to a natom_supa x 3 matrix of exponentials.

get_cell()

Get the set of lines which bound the unit cell and put in Jmol format.

get_global_index(*args)

This method is simply the inverse of the above one. input can take the following form get_global_index(‘Pb4’) get_global_index(‘Pb’,4) get_global_index((‘Pb’,4)) or get_global_index([‘Pb’,4])

get_mode_q(qvec, atpol_vec)

Create a poscar object with the atoms displaced along one of the 3n k-vec branches displaced by magnitude delta. qvec - This is the qvector.. atpol_vec - This is a vector, giving a linear combination of get_basis_q.

get_species_index(index, to_str=False)

This method will convert an atom index (within unit cell) to a (species,index) notation so you know which atom you are referring to. The default return is a tuple like (‘Pb’,4), if to_str is True it will convert the tuple to a string like ‘Pb4’

get_supa_fromk(kvec)

Given a k-vector or a list of k-vectors, find the smallest supercell which contains it/them. Possible input could be: “1/2,1/3,0 1/4,1/5,0” [“1/2,1/3,0”,”1/4,1/5,0”] [(1/2.,1/3.,0),(1/4.,1/5.,0)] (1/3.,1/4.,0) (Fraction(1,3),Fraction(1,4),0) [(Fraction(1,3),Fraction(1,4),0), (Fraction(1,2),Fraction(1,3),0)]

This routine will return a string of 9 integers that the supa method can take.

is_wscell_complete()

Check if the weight sums up correctly.

kill_atom(at)

Remove atoms from cell. This is not properly generalized yet, but it will get the job done for rasmol/povray.

label(inp)

Labels the atoms in the unit cell. must give a name for each species as the string ‘spec1 spec2...’.

make_orbitals()

Create a list of orbitals based on atom name. Names must belong to the dictionary below. If name is p or d, all p or d orbitals will be generated at that site.

outofcell(tol=0.98)

Translate basis atoms with direct coordinates above tol outside the unit cell.

pinfo()

Prints the volume and vector lengths and angles.

pposcar(ret='')

Prints the poscar.

prinfo()

Prints the reciprocal lattice information.

reorder(inp='')

Reorder the atoms

rescale(scale)

Rescales the unit cell.

rescale_atoms(scale)

Rescales the atoms only. Can be useful in obscure situations.

resetscale(scale)

Resets scale in structure constant (ie. structure NOT changed).

rot(inp, trans='')

Rotates the unit cell. user must supply 3x3 rotation matrix as the string ‘r11 r12 r13 r21 r22 r23...’

set_volume(vol)

Rescales the system to achieve the desired volume.

shift_atom(at, inp, coord='d')

Shift an individual atom by a b c where a,b,c are given in either direct or cartesian coordinates.

shift_atoms(shift, cartesian=True)

This method shifts all atoms by some matrix or constant, and returns self.

shift_origin(inp)

Shifts the origin of the unit cell by a b c where a,b,c are given in direct coordinates.

supa(inp, allincell=False)

Creates a supercell. user must supply 3x3 integer supercell matrix as the string ‘r11 r12 r13 r21 r22 r23...’

wigner_seitz(tol=1e-05, precision_renorm=True)

This method will compute the real space Wigner-Seitz unit cell, in an incremental way.