Density of States

Similar to the bands structure plot PyProcar goes beyond the conventional plain Density of states(DOS) plot to plot the projected DOS that carry more information. DOS plots in PyProcar have multiple functionalities(modes), plain, parametric, parametric_line, stack, stack_orbitals and stack_species. To read the information about DOS from the output of DFT calculations pyprocars depends on different files depending on the DFT package. In VASP PyProcar uses vasprun.xml while in elk it uses specific files generated by elk, given the elk.in PyProcar will resolve the files that need to be parsed. The Parameters used in this function are very similar to the ones in bandsplot.

We first explain the arguments involved in this function, then we explain the different mode using examples. Each argumnet will have a description, an example and a the dafault setting. If the desired setting matches the default, one does not need to specify that aregumnet.

Parameters

param vasprunfile

The most important argument needed dosplot is vasprunfile. vasprunfile defines the path to vasprun.xml from the density of states calculation. If plotting is being carried out in the directory of the calculation, one does not need to specify this argument.

example: vasprunfile='vasprun.xml'

default: vasprunfile='vasprun.xml'

param mode

mode defines the mode of the plot. This parameter will be explained in details with exmaples in the tutorial.

examples: mode='plain', mode='parametric', mode='parametric_line', mode='stack', mode='stack_orbitals', mode='stack_species'.

default: mode='plain'

param orientation

The orientation of the DOS plot.

examples: orientation='horizontal', orientation='vertical'

default: orientation='horizontal'

param spin_colors

spin_colors represent the colors the different spin ploarizations are going to be represented in the DOS plot. These colors can be chosen from any type of color acceptable by matplotlib(string,rgb,html).

examples: spin_colors=['blue','red'], spin_colors=[(0, 0, 1),(1, 0,0 )], spin_colors=['#0000ff','#ff0000']

default: spin_colors=['blue','red']

Caution

If the calculation is spin polarized one has to provide two colors even if one is plotting one spin. I disregard this cation if using default.

param colors

colors defines the color of plots filling the area under the curve of Total density of states. This is only important in the mode=stack, mode=stack_species, mode=stack_orbitals. To have a better sense of this parameter refer to the stack plots of SrVO3. These colors can be chosen from any type of color acceptable by matplotlib(string,rgb,html).

examples: colors=['blue','green','red','gray','orange','cyan','magenta']

default: colors=['red','green','blue','cyan','magenta','yellow',

'orange','purple','brown','navy','maroon','olive']

Caution

If the colors is defined, it has to be a python list(or numpy array) with enough elements that can cover the number of items being plotted in stack verion

param atoms

atoms define the projection of the atoms in the Density of States. In other words it selects only the contribution of the atoms provided. Atoms has to be a python list(or numpy array) containing the atom indices. Atom indices has to be order of the input files of DFT package. atoms is only relevant in mode='parametric', mode='parametric_line', mode='stack_orbitals'. keep in mind that python counting starts from zero

examples: for SrVO3 we are choosing only the oxygen atoms. atoms=[2,3,4], keep in mind that python counting starts from zero, for a POSCAR similar to following:

Sr1 V1 O3
1.0
3.900891 0.000000 0.000000
0.000000 3.900891 0.000000
0.000000 0.000000 3.900891
Sr V O
1 1 3
direct
0.500000 0.500000 0.500000 Sr atom 0
0.000000 0.000000 0.000000 V  atom 1
0.000000 0.500000 0.000000 O  atom 2
0.000000 0.000000 0.500000 O  atom 3
0.500000 0.000000 0.000000 O  atom 4

default: The default is set to select all the atoms.

param orbitals

orbitals define the projection of orbitals in the density of States. In other words it selects only the contribution of the orbitals provided. Orbitals has to be a python list(or numpy array) containing the Orbital indices. Orbitals indices has to be order of the input files of DFT package. The following table represents the indecies for different orbitals in VASP.

s

py

pz

px

dxy

dyz

dz2

dxz

x2-y2

0

1

2

3

4

5

6

7

8

orbitals is only relavent in mode='parametric', mode='parametric_line', mode='stack_species'.

examples: orbitals=[1,2,3] will only select the p orbitals while orbitals=[4,5,6,7,8] will select the d orbitals.

default: The default is set to select all the orbitals

param spins

spins represents the the spins asked to be plotted. By convention we consider 0 to be spin up and 1 to be spin down. spins has to be and array.

examples: spins=[0], spins=[1], spins=[0,1]

default: spins=[0,1]

param elimit

Energy window limit asked to plot. elimit has to be a two element python list(or numpy array).

example: elimit=[-2,2]

default: elimit=[emin,emax]

param cmap

The color map used for color coding the projections. cmap is only relevant in mode='parametric'. a full list of color maps is matplotlib are provided in this web page. <https://matplotlib.org/2.0.1/users/colormaps.html>_

example: cmap='plasma'

default: cmap='jet'

param vmax

The maximum value in the color bar. cmap is only relevant in mode='parametric'.

example: vmax=0.7

default: vmax=1.0

param vmin

The maximum value in the color bar. cmap is only relevant in mode='parametric'.

example: vmin=-1.0

default: vmax=0

param grid

Defines If a grid is plotted in the plot. The entry should be python boolian.

examples: grid=True, grid=False

dafault: grid=True

param savefig

savefig defines the file that the plot is going to be saved in. savefig accepts all the formats accepted by matplotlib such as png, pdf, jpg, … savefig=None. If not provided the plot will be shown in the interactive matplotlib mode.

examples: savefig='DOS.png', savefig='DOS.pdf'

defaults: No default is set for this parameter

param title

Defines the plot title asked to be added above the plot. If title is not defined, PyProcar will not add any title.

examples: title="Total Density of States SrVO_$3$". One can use LaTex format as well.

dafault: No default is set for this parameter.

param plot_total

If the total density of states is plotted as well as other options. The entry should be python boolian.

examples: plot_total=True, plot_total=False

default: plot_total=True

param code

Defines the Density Functional Theory code used for the calculation. The default of this argument is vasp, so if the calculation is done in vasp one does not need to define this argumnet.

examples: code=vasp, code=elk, code=abinit

default: code=vasp

param labels

labels define the legends plotted in defining each spin.

examples: labels=['Oxygen-Up','Oxygen-Down'], labels=['Oxygen-'+r'$\uparrow$','Oxygen-'+r'$\downarrow$'] Side note, r means the string will be treated as raw string. This has to be used if LaTex formating is used.

default: No default is used in the mode=plain, mode=parametric, mode=parametric_line. In mode=stack, mode=stack_species, mode=stack_orbitals the labels are generated automatically based on the other parameters such as atoms, orbitals

param items

items is only relavent for mode='stack'. stack will plot the items defined with stacked filled areas under curve. For clarification visit the examples in the tutorial. items need to be provided as a python dictionary, with keys being specific species and values being projections of orbitals. The following examples can clarify the python lingo.

examples: items={'Sr':[0],'O':[1,2,3],'V':[4,5,6,7,8]} or items=dict(Sr=[0],O=[1,2,3],V=[4,5,6,7,8]). The two examples are equivalent to each other. This will plot the following curves stacked on top of each other. projection of s orbital in Sr, projection of p orbitals in O and projection of d orbitals in V.

defalut: The default is set to take every atom and every orbital. Which will be equivalent to mode='stack_species'

param ax

ax is a matplotlib axes. In case one wants to put plot generated from this plot in a different figure and treat the output as a subplot in a larger plot.

example:

# Creates a figure with 3 rows and 2 colomuns
fig, axs = plt.subplots(3, 2)
x = np.linspace(-np.pi, np.pi, 1000)
y = np.sin(x)
axs[0, 0].plot(x, y)
pyprocar.dosplot(mode='plain',ax=axs[2, 2]),elimit=[-2,2])
plt.show()

default: None

mode and examples

1. mode='plain'

This mode plots the basic Total Density of States of the structure. This mode is set as the default mode of dosplot().

Usage:

pyprocar.dosplot(vasprunfile='vasprun.xml',
                 mode='plain',
                 elimit=[-4,4],
                 orientation='horizontal',
                 labels=[r'$\uparrow$',r'$\downarrow$'],
                 title=r'Total Density of States SrVO$_3$')
_images/dos_plain_hor.png

Note that vasprunfile, mode and orientation did not need to be specifies as we are using the defalut values. The following will be the change in usage of orientation, and the choice of the spin asked to be plotted. After this example we will switch back to horizontal plot for the examples. and plotting both of the spins in plots.

Usage:

pyprocar.dosplot(vasprunfile='vasprun.xml',
                 mode='plain',
                 elimit=[-4,4],
                 spins=[0],
                 orientation='vertical',
                 labels=[r'$\uparrow$',r'$\downarrow$'],
                 title=r'Total Density of States SrVO$_3$',
                 savefig='dos_plain_ver.png'
)
_images/dos_plain_ver.png

2. mode='parametric'

This mode will use color coding to illustrate the projection of atoms and orbitals asked to be projected. The following will plot shows the projection of p orbitals(orbitals=[1,2,3]) of O(atoms=[2,3,4]) in SrVO3

Usage:

pyprocar.dosplot(vasprunfile='vasprun.xml',
                 mode='parametric',
                 orbitals=[1,2,3],
                 atoms=[2,3,4],
                 elimit=[-4,4],
                 orientation='horizontal',
                 plot_total=True,
                 title=r'Projected DOS of p orbitals of Oxygen in SrVO$_3$')
_images/dos_parametric.png

3. mode='parametric_line'

This mode might be the most familiar mode to the users. This mode will use curves to plot the projected density of states. The following will plot shows the projection of p orbitals(orbitals=[1,2,3]) of O(atoms=[2,3,4]) in SrVO3

Usage::
pyprocar.bandsdosplot(vasprunfile=’vasprun.xml’,

mode=’parametric_line’, orbitals=[1,2,3], atoms=[2,3,4], elimit=[-4,4], labels=[‘O-up’,’O-down’], plot_total=True)

_images/dos_parameteric_line.png

4. mode='stack'

This mode plots the contribution of the species and their specified orbitals as stacked curves with filled areas under the curves. The following example represents the stacked projected DOS of d orbitals of Sr(Sr=[4,5,6,7,8]), p orbitals of O(O=[1,2,3]) and the s and p orbitals of V(V=[0,1,2,3]). In this example we have specified colors to have an example for not using the default colors.

Usage:

pyprocar.dosplot(vasprunfile='vasprun.xml',
                 mode='stack',
                 colors=['lawngreen','orangered','royalblue'],
                 items=dict(Sr=[4,5,6,7,8],O=[1,2,3],V=[0,1,2,3]),
                 orientation='horizontal',
                 elimit=[-4,4],
                 plot_total=True)
_images/dos_stack.png

5. mode='stack_species'

This mode is a more specified version of mode=='stack'. This mode will plot the selected orbitals for all the species. The plot will be stached curves with filled areas under the curve. This mode will plot the selected orbitals for all the species. For example if orbitals=[1,2,3], PyProcar will plot all the p orbitals of all the species. If no orbital is specifies, it will plot the projection over all the species. The following example is representing the stacked curves for all species, without orbitals defined(i.e. sum over all the orbitals)

Usage:

pyprocar.dosplot(vasprunfile=vasprun,
                 mode='stack_species',
                 orientation='horizontal',
                 elimit=[-4,4],
                 plot_total=True)
_images/dos_stack_species.png

6. mode='stack_orbitals'

This mode is another variation of mode=='stack', This mode will plot the selected atoms for all the orbitals. The list of atoms do not need to be from the same species. The following example shows all the orbitals of Oxygen(atoms=[2,3,4])

Usage:

pyprocar.dosplot(vasprunfile=vasprun,
                 mode='stack_orbitals',
                 atoms=[2,3,4],
                 orientation='horizontal',
                 elimit=[-4,4],
                 plot_total=True)
_images/dos_stack_orbitals.png

Created on May 17 2020 @author: Pedram Tavadze

pyprocar.scriptDosplot.dosplot(vasprunfile='vasprun.xml', mode='plain', orientation='horizontal', spin_colors=None, colors=None, spins=None, atoms=None, orbitals=None, elimit=None, cmap='jet', vmax=None, vmin=None, grid=True, savefig=None, title=None, plot_total=True, code='vasp', labels=None, items={}, ax=None)

This function plots density of states