Package: pydass_vasp
Convenient Python modules and wrapping script executables.Example: plotting band structurepydass_vasp.plotting.plot_bs(axis_range=[-4,6])Returned dictionary:{'data':{'columns':['k_points','band_1','band_2','band_3','band_4','band_5','band_6','band_7','band_8','band_9','band_10','band_11','band_12','band_13','band_14','band_15','band_16','band_17','band_18','band_19','band_20','band_21','band_22','band_23','band_24','band_25','band_26','band_27','band_28','band_29','band_30','band_31','band_32'],'data':array([[0.,-20.342219,-16.616756,...,5.849101,5.855091,6.074841],[0.04558028,-20.342181,-16.616823,...,5.811826,5.815311,6.060851],[0.09116057,-20.34223,-16.617067,...,5.730248,5.734556,5.80481],...,[2.49869989,-20.343194,-16.628521,...,5.172637,5.204402,5.711173],[2.53591604,-20.343228,-16.6286,...,5.219897,5.226956,5.730676],[2.57313218,-20.34319,-16.628622,...,5.234177,5.234205,5.726715]])},'reciprocal_point_locations':array([0.,0.8660254,1.3660254,1.8660254,2.57313218]),'reciprocal_points':['R','G','X','M','G']}Example: plotting total density of states with spin polarizationpydass_vasp.plotting.plot_tdos(axis_range=[-15,15,0,40],return_refs=True)Returned dictionary:{'ax_spin_combined':<matplotlib.axes._subplots.AxesSubplotat0x108b95110>,'ax_spin_overlapping':<matplotlib.axes._subplots.AxesSubplotat0x10b0f5fd0>,'data_spin_down':{'columns':['E','total_down','integrated_down'],'data':array([[-22.63140452,0.,0.],[-22.60640452,0.,0.],[-22.58040452,0.,0.],...,[15.05159548,0.,56.],[15.07659548,0.,56.],[15.10159548,0.,56.]])},'data_spin_up':{'columns':['E','total_up','integrated_up'],'data':array([[-22.63140452,0.,0.],[-22.60640452,0.,0.],[-22.58040452,0.,0.],...,[15.05159548,0.,56.],[15.07659548,0.,56.],[15.10159548,0.,56.]])}}What is it?This Python package is the result of frustration of searching for an
organized, straightforward and flexible approach of plotting, fitting
and manipulation ofVASPfiles (typicallyPOSCAR) in a few key strokes as long as you have a terminal, and
preferably a (S)FTP client. It has the following features:It is a Python package with a straightforward structure. When youimport pydass_vasp, you have sub-packagespydass_vasp.plotting,pydass_vasp.fitting,pydass_vasp.manipulation,pydass_vasp.xml_utils, each
containing a few functions to carry out your tasks, with a careful
selection of options to choose from. Return values are Python
dictionaries, informative enough to be flexible for post-processing.
When there is no need for an object, don’t bother creating one.It also has scripts that utilize the main package. They are simply
‘wrappers’ to the functions that are used the most frequently,
typicallyplottingandfittingfunctions. Instead ofcding into a directory and launching the Python interpreterpython, making the imports and calling the functions, you just
need to stay in your terminal shell and typeplot_tdos.pyto plot
the total density of states (DOS),plot_ldos.py 1to plot the
local projected DOS of the first atom, andplot_bs.pyto plot the
band structure. These scripts accept arguments and options as
flexible as their function counterparts.The defaults of the functions and wrapping scripts are sane and cater
to the most use cases. For example, If you are in a Python
interpreter, simply typing inpydass_vasp.plotting.plot_tdos()will collect data to plot fromDOSCARand parameters necessary
under the current VASP job directory, generate anddisplaya
figure (or more) butnot saveit/them on disk, and at the same
time return a dictionary with the extracted data. It’ll automatically
obtain critical parameters such asISPIN,E-fermifirst from
VASPoutputfiles (e.g.OUTCAR), theninputfiles (e.g.INCAR) if the first attempt fails, and decide the number of
figures to generate. If you are just in a terminal shell, typing in
the scriptplot_tdos.pywill do the same, butrather than
displaythe figure(s), instead,saveit/them quietly and use
matplotlib’sAggbackend. This would be particularly helpful for
terminal users who don’t have X Window forwarding
(Xmingfor Windows,XQuartzfor Mac OS X)
set up on their own local machine, or the forwarding connection is
slow to hold the live generated figures.The options to the functions and wrapping scripts provide you with
room of customization from the beginning. For example, the internal
documentation ofpydass_vasp.plotting.plot_tdos()looks like
below.# see the docstring# in IPython interpreterpydass_vasp.plotting.plot_tdos?# or in regular python interpreterhelp(pydass_vasp.plotting.plot_tdos)Plot the total density of states, with consideration of spin-polarization.
Accepts input file 'DOSCAR', or 'vasprun.xml'.

Parameters
----------
axis_range: list
    the range of axes x and y, 4 values in a list
ISPIN: int
    user specified ISPIN
    If not given, for DOSCAR-type input, infer from OUTCAR/INCAR.
    For vasprun.xml-type input, infer from 'vasprun.xml'.
input_file: string
    input file name, default to 'DOSCAR'
    For DOSCAR-type, can be any string containing 'DOSCAR'.
    For vasprun.xml-type input, can be any string ending with '.xml'.
display: bool
    Display figures or not. Default to True.
on_figs: list/int
    the current figure numbers to plot to, default to new figures
return_refs: bool
    Return the axes reference(s) drawing or not. Default to False.
save_figs: bool
    Save figures or not. Default to False.
save_data: bool
    Save data or not. Default to False.
output_prefix: string
    prefix string before the output files, default to 'TDOS'
return_states_at_Ef: bool
    Calculate the TDOS at Ef with a 0.4 eV window of integration or not. Default to False.

Returns
-------
a dict, containing
    'data': a dict that has 2D array of data,
        easily to Pandas DataFrame by pd.DataFrame(**returned_dict['data'])
    'ax': the axes reference, if return_refs == TrueThe returned dictionary also leave room for adjustments. Takepydass_vasp.plotting.plot_tdos(return_refs=True)as an example.returned_dict={'data':{'columns':col_names,'data':data}'ax':ax}returned_dict['data']has a 2D numpy array of data, and their
column names. This construction is prefered because if you havepandas, you can just convert it to a
DataFrame bypd.DataFrame(**returned_dict['data']).returned_dict['ax']is the matplotlib axes reference. WhenISPINis 2, they are two elements:'ax_spin_up'and'ax_spin_down'.It has a uniform plotting support for the Crystal Orbital Hamilton
Populations (COHP) analysis toolLOBSTER,
functionpydass_vasp.plotting.plot_cohp()and scriptplot_cohp.py.If you use matplotlib >= 1.4, and you plot with the wrapping scripts,
you can optionally enjoy the aesthetic enhancement powered by its
newly added sub-packagestyle. For
example,plot_tdos.py--style=ggplotswitches on the style ofggplot. Read the stylesheetguidefor more
info, including designing and loading your own styles.More on optionsAs an example, we again considerpydass_vasp.plotting.plot_tdos(),
shortened asplot_tdos().plot_tdos(input_file='vasprun.xml')switches from taking inDOSCARtovasprun.xml. It lets you select what file you prefer
to use. Any filename containing'DOSCAR'is considered to be ofDOSCARtype, any filename ending with'.xml'is considered to be
ofvasprun.xmltype.plot_tdos(ISPIN=2)lets you manually override the auto-detection ofISPINfrom files other thanDOSCAR. The program will skip the
corresponding part of work. This is helpful when you only have the major
data fileDOSCARtransferred to you local machine, and do not have
the other files necessary to extract the parameters to proceed plotting.
To leave no confusion, whenISPINis 2, two figures are generated,
one with spin up and down combined, the other with two overlapping
curves, denoting spin up and spin down separately.plot_tdos(on_figs=1)creates the plot on top of an existing
matplotlib figure labeled asFigure 1, instead of generating a whole
new one.plot_tdos(on_figs=[1,2])whenISPINis 2 puts the two plots
mentioned before ontoFigure 1andFigure 2.plot_tdos(on_figs=[1,None])is also valid, meaning putting the
combined curve toFigure 1, and the two overlapping curves to a new
figure, which you can of course delete on its own.plot_tdos(display=False, save_figs=True)replicates the behavior of
the corresponding wrapping scriptplot_tdos.py.plot_tdos(return_refs=True)adds the matplotlib axes reference(s) to
the returned dictionary, and keeps the figure(s) open to let you make
further changes. Note: you don’t need to switchdisplayon to get
axes references.plot_tdos(save_data=True,output_prefix='TDOS')saves the extracted
data to disk, with the prefix'TDOS'. The argumentoutput_prefixalso specifies the filenames for saved figures.The wrapping scriptplot_tdos.pyaccepts the relevant options in the
form of-ivasprun.xml, or--inputvasprun.xml,-por--display. For more readily available information, type inplot_tdos.py-hto get help direclty from the terminal shell.DependenciesPython 2.7 (Python 3 support is currently not considered)NumPySciPymatplotlibIPython (optional, but better to have)I highly recommend every scientist/researcher who is new to Python to
install the scientific superpackAnaconda, if you are
using Windows or Mac OS X. Even if you are on Linux, it is still highly
recommended if you don’t have superuser control over the machine to
install packages freely. It is often the case when you have ssh access
to a supercomputer. In all these cases, just download the package and do
a simple local installation, and you already have everything to start
with, not only forpydass_vasp, but also for the whole adventure of
scientific computing.Installation[STRIKEOUT:This package has already been registered on PyPI.] So if you
havepip, which is a must
have, and should already have been included in Anaconda,[STRIKEOUT:pip install pydass_vasp][STRIKEOUT:Or] if you wish to follow the more updated releases, which
should serve you better because small projects can fully enjoy the
freedom of updates on GitHub before committing to PyPI,pip install git+https://github.com/terencezl/pydass_vaspAlternatively, if you don’t have pip, [STRIKEOUT:download the.tar.gzfile from the PyPI page and decompress it in a local
directory of your choice, or]git clonehttps://github.com/terencezl/pydass_vasp, get into the
outerpydass_vaspdirectory andpython setup.py install

# then you can get out of that directory and just delete it
cd ..
rm -r pydass_vaspHowever,pipinstallation is always recommended, because of the ease
of uninstallation,pip uninstall pydass_vaspGetting HelpAn organized tutorial/documentation has not been ready yet, but the
docstrings of functions are fairly complete. If you useIPython, which is also a must have, and should
already have been included in Anaconda,importpydass_vasp# in IPython interpreterpydass_vasp.plotting.plot_tdos?# or in regular python interpreterhelp(pydass_vasp.plotting.plot_tdos)You will get help. Experiment on a few options and you’ll be quickly on
your way.In addition, the help texts of scripts (option-hwhen you call them
in the terminal shell) are available as well.