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.

All the arguments invloved in this function are exmplaed in the API of this function that can be found in the following link in the end of this document. 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. The following section will provide examples of the usage of each mode of plotting.

Note

To copy the example you can easily use the copy button in the right top corner of each example.

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().

>>>  pyprocar.dosplot(filename='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 filename, 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.

>>>  pyprocar.dosplot(filename='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

>>>  pyprocar.dosplot(filename='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

>>>  pyprocar.bandsdosplot(filename='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.

>>>  pyprocar.dosplot(filename='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)

>>>  pyprocar.dosplot(filename=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])

>>>  pyprocar.dosplot(filename=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(filename='vasprun.xml', mode='plain', interpolation_factor=None, orientation='horizontal', spin_colors=None, colors=None, spins=None, atoms=None, orbitals=None, elimit=None, dos_limit=None, cmap='jet', linewidth=1, vmax=None, vmin=None, grid=False, savefig=None, title=None, plot_total=True, code='vasp', labels=None, items={}, ax=None, plt_show=True, verbose=True)[source]

This function plots the density of states in different formats

Parameters
  • filename (str, optional (default 'vasprun.xml')) –

    The most important argument needed dosplot is filename. filename 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.

    e.g. filename='~/SrVO3/DOS/vasprun.xml'

  • mode (str, optional (default 'plain')) –

    mode defines the mode of the plot. This parameter will be explained in details with exmaples in the tutorial. options are 'plain', 'parametric', 'parametric_line', 'stack', 'stack_orbitals', 'stack_species'.

    e.g. mode='stack'

  • interpolation_factor (int, optional (default None)) –

    Number of points in energy axis is multiplied by this factor and interpolated using cubic spline.

    e.g. interpolation_factor=3

  • orientation (str, optional (default horizontal')) –

    The orientation of the DOS plot. options are 'horizontal', 'vertical'

    e.g. orientation='vertical'

  • spin_colors (list str or tuples, (optional ``spin_colors=[‘blue’,) –

    ‘red’]``) 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).

    e.g. spin_colors=['blue','red'], spin_colors=[(0, 0, 1),(1, 0,0 )], spin_colors=['#0000ff','#ff0000']

    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.

  • colors (list str or tuples, optional (default, optional)) –

    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).

    e.g. colors=['red', 'blue', 'green', 'magenta', 'cyan']

  • spins (list int, optional) –

    spins defines plotting of different spins channels present in the calculation, If the calculation is spin non-polorized the spins will be set by default to spins=[0]. if the calculation is spin polorized this parameter can be set to 0 or 1 or both.

    e.g. spins=[0, 1]

  • atoms (list int, optional) –

    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. e.g. 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
    

    if nothing is specified this parameter will consider all the atoms present.

  • orbitals (list int, optional) –

    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'.

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

    If nothing is specified pyprocar will select all the present orbitals.

  • elimit (list float, optional) –

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

    e.g. elimit=[-2, 2] The default is set to the minimum and maximum of the energy window.

  • dos_limit (list float, optional) –

    dos_limit defines the density of states axis limits on the graph. It is automatically set to select 10% higher than the maximum of density of states in the specified energy window.

    e.g. dos_limit=[0, 30]

  • cmap (str , optional (default 'jet')) –

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

    e.g. cmap='plasma'

  • linewidth (str, optional (default 1)) –

    The line width with which the total DOS is ploted

    e.g. linewidth=2

  • vmax (float, optional) –

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

    e.g. vmax=1.0

  • vmin (float, optional) –

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

    e.g. vmin=-1.0

  • grid (bool, optional (default Flase)) –

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

    e.g. grid=True

  • savefig (str , optional (default None)) –

    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, … If not provided the plot will be shown in the interactive matplotlib mode.

    e.g. savefig='DOS.png', savefig='DOS.pdf'

  • title (str, optional) –

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

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

  • plot_total (bool, optional (default True)) –

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

    e.g. plot_total=True

  • code (str, optional (default 'vasp')) –

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

    e.g. code=vasp, code=elk, code=abinit

  • labels (list str, optional) –

    labels define the legends plotted in defining each spin.

    e.g. labels=['Oxygen-Up','Oxygen-Down'], labels=['Oxygen-'+r'$\uparrow$','Oxygen-'+r'$\downarrow$'] Side means the string will be treated as raw string. This has to be used if LaTex formating is used. No default is used in the mode=plain, mode=parametric, mode=parametric_line. In mode=stack, ack_species`, mode=stack_orbitals the labels are generated automatically based on the other parameters such as atoms and orbitals.

  • items (dict, optional) –

    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.

    e.g. 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. The default is set to take every atom and every orbital. Which will be equivalent to mode='stack_species'

  • ax (matplotlib ax object, optional) –

    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.

    e.g.

    >>> # 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()
    

  • plt_show (bool, optional (default True)) –

    whether to show the generated plot or skip to the saving.

    e.g. plt_show=True

Returns

  • fig (matplotlib figure) – The generated figure

  • ax (matplotlib ax object) – The generated ax for this density of states. If one chooses plt_show=False, one can modify the plot using this returned object. e.g.

    >>> fig, ax = pyprocar.dosplot(mode='plain', plt_show=False)
    >>> ax.set_ylim(-2,2)
    >>> fig.show()