rad-plot-dos.py#

Changed in version 0.5.21: Renamed from rad-dos-plotter.py

Script for visualization of projected density of states. It supports the result of the calculation from:

Quantum Espresso (projwfc.x).
All type of calculations are supported (Collinear, spin-unpolarized; collinear, spin-polarized; non-collinear, non-spin-orbit; non-collinear, spin-orbit)

When summation over the atoms of the same type is involved PDOS is just summed. In contrary, when the summation over k-points is involved, PDOS is summed and divided by the number of k points.

K-resolved PDOS are handled by summing over kpoints (and dividing by the number of kpoints).

There are two ways to use this script:

Predefined plots
Custom plots

Examples of predefined plots for each type of calculations (all commands for the command line are executed from "docs/examples/rad-plot-dos" folder):

Usage examples

Before we discuss the difference between those two types, we describe parameters, which affects both of them

Common remarks#

Script tries to detect all seednames present in -if, --input-folder by default, unless -s, --seedname option specifies particular seedname to work with.

Plot styles#

There are two main plot style:

Default

PDOS of each projector appears on the separate plot within the same figure.

rad-plot-dos.py --custom "Ni (d)" "I (p)" -if collinear-spin-polarized/ -ew -7 -2 -on style-examples/

../../../_images/custom.png — Default style#

Relative (-r, --relative)
PDOS of all projectors appear on the same plot, PDOS of each projector starts at the end of the previous projector`s PDOS.
rad-plot-dos.py -r --custom "Ni (d)" "I (p)" -if collinear-spin-polarized/ -ew -7 -2 -on style-examples/
Relative style#

Each of these styles could be modified by the following "substyles":

Normalized (-n, --normalize)

PDOS of each projector is normalized with respect to the local DOS. Local DOS could be the sum of all PDOS, as well as total PDOS (see -bt, --background-total).

rad-plot-dos.py -n --custom "Ni (d)" "I (p)" -if collinear-spin-polarized/ -ew -7 -2 -on style-examples/

../../../_images/custom2.png — With default style#

rad-plot-dos.py -r -n --custom "Ni (d)" "I (p)" -if collinear-spin-polarized/ -ew -7 -2 -on style-examples/

../../../_images/custom3.png — With relative style#

Total as a background (-bt, --background-total)

Total PDOS is used as the background values instead of the sum of the PDOS from the plot (which is used by default).

rad-plot-dos.py -bt --custom "Ni (d)" "I (p)" -if collinear-spin-polarized/ -ew -7 -2 -on style-examples/

../../../_images/custom4.png — With default style#

rad-plot-dos.py -r -bt --custom "Ni (d)" "I (p)" -if collinear-spin-polarized/ -ew -7 -2 -on style-examples/

../../../_images/custom5.png — With relative style#

Both of them

rad-plot-dos.py -n -bt --custom "Ni (d)" "I (p)" -if collinear-spin-polarized/ -ew -7 -2 -on style-examples/

../../../_images/custom6.png — With default style#

rad-plot-dos.py -r -n -bt --custom "Ni (d)" "I (p)" -if collinear-spin-polarized/ -ew -7 -2 -on style-examples/

../../../_images/custom7.png — With relative style#

In addition one could modify the colours used in the relative or custom plots with the -cls, --colours parameter.

-alfs, --axes-labels-fontsize, -lfs, --legend-fontsize and -tfs, --title-fontsize provide control of the fontsizes.

Fermi energy#

-ef, --efermi allows to shift zero to the value of Fermi energy. If energy is shifted to Fermi, then in the axis labels one would have \(\text{E}-\text{E}_{Fermi}, \text{eV}\). Otherwise the label would be \(\text{E}, \text{eV}\).

-ew, --energy-window and -dw, --dos-window allows to specify energy and states/eV windows.

Interactive plot#

-i, --interactive opens each plot in an interactive matplotlib window. It allows one to modify the range and appearance of the plot (to drag the legend).

Output remarks#

For each seedname a separate folder "seedname-suffix" is created.

Suffix is a combination of any number of the following words:

"separate" - appears if -sep, --separate option is used.
"relative" - appears if -r, --relative option is used.
"normalized" - appears if -n, --normalize option is used.
"vstotal" - appears if -bt, --background-total option is used.

Note

-sep, --separate option contribute to the suffix in both cases, but affects only the Predefined plots.

The structure of the output folder is the following:

output_path/
├── ....
├── seedname_1-suffixes/
├── ...
└── seedname_n-suffixes/

By default only the pictures (.png) are created. Two additional formats of the output are:

Output formats#

txt (-st, --save-txt)
Content of the plots in txt format. First line is the header with projectors. It has the same name as the corresponding picture, but the extension is ".txt".

pickle (-sp, --save-pickle)

Python-specific format, which allowed to pick up the figure from the python code and modify it:

import pickle
import matplotlib.pyplot as plt

fig = pickle.load(open('filename.pickle', 'rb'))
axes = fig.get_axes()

for ax in axes:
    ax.set_xlabel("Custom x label")
    ax.set_ylabel("Custom y label")
    ax.set_title("Custom title")

fig.savefig("filename.png", dpi=400, bbox_inches="tight")

If fig.show() or plt.show() does not work the following fix may help (credit):

def show_figure(fig):
    dummy = plt.figure()
    new_manager = dummy.canvas.manager
    new_manager.canvas.figure = fig
    fig.set_canvas(new_manager.canvas)

show_figure(fig)
plt.show()

Custom plots#

Hint

-lbs, --labels allows to provide custom labels for the plot. Amount of labels have to be the same as the amount of custom strings, or one more. If one more, then first one is interpreted as the label for the background (Use "None" to switch it off).

Custom plots allows the user to create plots with the hand-picked PDOS.

In order to get custom plot one have to provide --custom argument.

As a parameters this argument requires any number of strings, where each string specifies one PDOS for the plot. This string specifies the set of atoms and projectors, which are summed to produce PDOS.

Note

In reality projector specify the set of projectors: \(p\) but not \(p_x\)

The following rules apply to the construction of the input string:

atom_type is required
Each string can correspond only to one atom type.
Atom numbers (n1 and n2) are optional.
Each atom number is preceded by exactly one "#" symbol. If no numbers are provided, then the sum is carried out over all atoms of the type atom_type.
Projectors section is optional.
Projector section is enclosed in parenthesis. It is either absent or contains at least one projector_type. If projectors are not specified, then the sum is carried out over all projectors for each atom.
Projectors are separated by commas.
Each comma has to be preceded and followed by the projector.
Projector numbers (m1, m2, k2, k2) are optional.
Each projector number is preceded by exactly one "#" symbol. If no numbers are provided for projector_type, then the sum is carried out over all projectors of the type projector_type for each atom.
Spaces are ignored.
Feel free to add as many spaces as you wish. Keep in mind that input string serves as a label in the plot as is.
Entries for different atom_type are separated by ";"
Each ";" has to preceded and followed by the entry.

The format of the string:

atom_type#n1#n2... (projector_type1#m1#m2, projector_type2#k1#k2, ...); ...

Here is an example of the set of PDOS file from projwfc.x output:

seedname.pdos_atm#1(Ni)_wfc#1(s)
seedname.pdos_atm#1(Ni)_wfc#2(p)
seedname.pdos_atm#1(Ni)_wfc#3(d)
seedname.pdos_atm#1(Ni)_wfc#4(s)
seedname.pdos_atm#2(I)_wfc#1(s)
seedname.pdos_atm#2(I)_wfc#2(p)
seedname.pdos_atm#3(I)_wfc#1(s)
seedname.pdos_atm#3(I)_wfc#2(p)

Where the colour code specify the correspondence of the input string parts to the projwfc.x output files.

Here are few examples of the input strings:

"Ni"
Sums over all projectors of Ni: 1-4. Equivalent to: "Ni#1" or "Ni (s, p, d)" or "N i"
"Ni; I"
Sums over all projectors of Ni and I: 1-8.
"Ni (s#1, d)"
Sums over one s and d projector of Ni: 1, 3
"I"
Sums over all projectors of all I atoms: 5-8. Equivalent to "I#2#3 (s, p)"
"I#3 (p)"
Sums over p projector of the second I atom: 8.
"I (p#2)"
Sums over p projector of all I atoms: 6, 8. Equivalent to "I (p)" or "I#2#3 (p)"

Output file of the custom plot is located in the output folder with the name "custom.png" (with corresponding txt or pickle output if any). If "custom.png" already exists in the output folder, then integer number is added to the end ("custom1.txt") in order to prevent accidental loss of the previous files. Integer is the smallest one, which provides unique name.

Predefined plots#

The predefined plots are:

pdos-vs-dos.png
Total partial density of states (sum over all projectors) vs total density of states (directly from the plane-wave basis). Affected by -sp, --save-pickle.
atomic-contributions.png
Contribution of each atom (summed over all projectors) into the total partial density of states. Affected by -sp, --save-pickle. Affected by -st, --save-txt.
atom-resolved/
Contribution of each projectors group (i.e. \(s\), \(p\), \(d\), \(f\)) into the partial density of state of each atom. Affected by -sp, --save-pickle. Affected by -st, --save-txt.
orbital-resolved/
Contribution of each projector (i. e. \(p_z\), \(p_x\), \(p_y\)) into the total partial density of states of each group (i.e. \(p\)). Affected by -sp, --save-pickle. Affected by -st, --save-txt.

Option -sep, --separate plots PDOS individually for each atom.

Each seedname folder has the structure:

seedname/
├── pdos-vs-dos.png
├── atomic-contributions.png
├── atom-resolved/
│   ├── output_name_1
│   └── output_name_2
└── orbital-resolved/
    ├── output_name_1
    └── output_name_2

Arguments#

-if, --input-folder#

Relative or absolute path to the folder with PDOS files.

default: "."
type: str

Changed in version 0.8.0: Renamed from input_path

-s, --seedname#

Prefix for input files with PDOS(E).

In the case of Quantum Espresso-produced seedname is the same as specified in the QE projwfc.x input file (filpdos).

If it is not provided the script tries to detect it automatically in the rad-plot-dos_input-folder folder.

optional
type: str

Changed in version 0.5.21: from "filpdos" to "seedname".

-on, --output-name#

Relative or absolute path to the folder for saving outputs.

default: ""
type: str

-ew, --energy-window#

Energy window for the plots.

By default the whole energy range present in the files is plotted.

optional
type: tuple of 2 float

Changed in version 0.5.21: Renamed from "window" to "energy-window".

-dw, --dos-window#

DOS window for the plots.

By default the whole states/eV range is plotted.

optional
type: tuple of 2 float

New in version 0.5.21.

-ef, --efermi#

Fermi energy.

Zero is shifted to Fermi energy.

default: 0.0
type: float

-sep, --separate#

Whether to plot projected DOS for each atom of the same type separately.

default: False
type: bool

-r, --relative#

Whether to use relative style.

default: False
type: bool

-n, --normalize#

Whether to normalized PDOS values to 1.

(with respect to LDOS of each plot or to total PDOS if -bt, --background-total is used).

default: False
type: bool

-v, --verbose#

Verbose output, propagates to the called methods.

default: False
type: bool

-i, --interactive#

Interactive plotting.

default: False
type: bool

-sp, --save-pickle#

Whether to save figures as .pickle files.

default: False
type: bool

New in version 0.5.21.

-st, --save-txt#

Whether to save some data as txt files.

It does not affect "pdos-vs-dos.png", because these data are accessible directly from PDOS input files.

default: False
type: bool

New in version 0.5.21.

-bt, --background-total#

Whether to use total PDOS as the background for all plots.

default: False
type: bool

New in version 0.5.21.

--custom#

Custom PDOS plot. See Custom plots for info.

optional
type: list of str

New in version 0.7.5.

-cls, --colours#

Colours for the relative and custom plots.

Values are passed directly to the matplotlib as strings, therefore any valid value is allowed. Examples: "red" or "#FF0000". When custom is used the order of colours is the same as for the values of the custom.

optional
type: list of str

New in version 0.7.5.

-lbs, --labels#

Labels for the custom plots.

Amount of labels have to be the same as the amount of custom strings, or one more. If one more, then first one is interpreted as the label for the background (Use "None" to switch it off). If the amount of argument is one more and the first one is None, then the label for the total PDOS is switched off and the total PDOS itself is not plotted.

optional
type: list of str

New in version 0.7.6.

-lfs, --legend-fontsize#

Fontsize of the legend.

default: 12
type: int

New in version 0.7.8.

-alfs, --axes-labels-fontsize#

Fontsize of the labes of the axes.

default: 14
type: int

New in version 0.7.8.

-tfs, --title-fontsize#

Fontsize of the title.

default: 18
type: int

New in version 0.7.8.