Dos¶

class py4vasp.data.Dos(raw_data)¶

Bases: py4vasp.data._base.DataBase, py4vasp.data._export.Image

The electronic density of states (DOS).

You can use this class to extract the DOS data of a Vasp calculation. Typically you want to run a non self consistent calculation with a denser mesh for a smoother DOS, but the class will work independent of it. If you generated orbital decomposed DOS, you can use this class to select which subset of these orbitals to read or plot.

Parameters

raw_dos (RawDos) – Dataclass containing the raw data necessary to produce a DOS.

Methods Summary

from_dict(dict_)	Initialize refinement class from data dictionary
from_file([file])	Read the data dictionary from the given file.
plot([selection])	Read the data and generate a plotly figure.
print()	Print a string representation of this class to standard output.
read([selection])	Read the data into a dictionary.
to_dict([selection])	Read the data into a dictionary.
to_frame([selection])	Read the data into a pandas DataFrame.
to_image(*args[, filename])	Read the data and generate an image writing to the given filename.
to_plotly([selection])	Read the data and generate a plotly figure.

Methods Documentation

classmethod from_dict(dict_)¶

Initialize refinement class from data dictionary

Parameters

data_dict (dict) – Data dictionary that contains one or more different raw data sources.

classmethod from_file(file=None)¶

Read the data dictionary from the given file.

You want to use this method if you want to avoid using the Calculation wrapper, for example because you renamed the output of the VASP calculation.

Parameters

file (str or Path or raw.File) – Filename from which the data is extracted. If not present the default filename is used. Alternatively, you can open the file yourself and pass the File object. In that case, you need to take care the file is properly closed again and be aware the generated instance of this class becomes unusable after the file is closed.

Returns

The returned instance handles opening and closing the file for every function called on it, unless a File object in which case this is left to the user.

Return type

DataBase

plot(selection=None)¶

Read the data and generate a plotly figure.

Parameters

• selection (str) –

  A string specifying the projection of the orbitals. There are three distinct possibilities:

  • To specify the atom, you can either use its element name (Si, Al, …) or its index as given in the input file (1, 2, …). For the latter option it is also possible to specify ranges (e.g. 1:4).

  • To select a particular orbital you can give a string (s, px, dxz, …) or select multiple orbitals by their angular momentum (s, p, d, f).

  • For the spin, you have the options up, down, or total.

  You separate multiple selections by commas or whitespace and can nest them using parenthesis, e.g. Sr(s, p) or s(up), p(down). The order of the selections does not matter, but it is case sensitive to distinguish p (angular momentum l = 1) from P (phosphorus).

• source (str, optional) – If you used a KPOINTS_OPT file to use a second k-point mesh, you can provide a keyword argument source=”kpoints_opt” to use the k-points defined in that file instead of the one specified in KPOINTS.

Returns

plotly figure containing the total DOS. If the calculation was spin polarized, the resulting DOS is spin resolved and the spin-down DOS is plotted towards negative values. If a selection the orbital resolved DOS is given for the specified projectors.

Return type

plotly.graph_objects.Figure

Examples

Select the p orbitals of the first atom in the POSCAR file:

>>> calc.dos.plot(selection="1(p)")

Select the d orbitals of Mn, Co, and Fe:

>>> calc.dos.plot("d(Mn, Co, Fe)")

Select the spin-up contribution of the first three atoms combined

>>> calc.dos.plot("up(1:3)")

print()¶

Print a string representation of this class to standard output.

read(selection=None)¶

Read the data into a dictionary.

Parameters

• selection (str) –

  A string specifying the projection of the orbitals. There are three distinct possibilities:

  • To specify the atom, you can either use its element name (Si, Al, …) or its index as given in the input file (1, 2, …). For the latter option it is also possible to specify ranges (e.g. 1:4).

  • To select a particular orbital you can give a string (s, px, dxz, …) or select multiple orbitals by their angular momentum (s, p, d, f).

  • For the spin, you have the options up, down, or total.

  You separate multiple selections by commas or whitespace and can nest them using parenthesis, e.g. Sr(s, p) or s(up), p(down). The order of the selections does not matter, but it is case sensitive to distinguish p (angular momentum l = 1) from P (phosphorus).

• source (str, optional) – If you used a KPOINTS_OPT file to use a second k-point mesh, you can provide a keyword argument source=”kpoints_opt” to use the k-points defined in that file instead of the one specified in KPOINTS.

Returns

Contains the energies at which the DOS was evaluated aligned to the Fermi energy and the total DOS or the spin-resolved DOS for spin-polarized calculations. If available and a selection is passed, the orbital resolved DOS for the selected orbitals is included.

Return type

dict

Examples

Select the p orbitals of the first atom in the POSCAR file:

>>> calc.dos.read(selection="1(p)")

Select the d orbitals of Mn, Co, and Fe:

>>> calc.dos.read("d(Mn, Co, Fe)")

Select the spin-up contribution of the first three atoms combined

>>> calc.dos.read("up(1:3)")

to_dict(selection=None)¶

Read the data into a dictionary.

Parameters

• selection (str) –

  A string specifying the projection of the orbitals. There are three distinct possibilities:

  • To specify the atom, you can either use its element name (Si, Al, …) or its index as given in the input file (1, 2, …). For the latter option it is also possible to specify ranges (e.g. 1:4).

  • To select a particular orbital you can give a string (s, px, dxz, …) or select multiple orbitals by their angular momentum (s, p, d, f).

  • For the spin, you have the options up, down, or total.

  You separate multiple selections by commas or whitespace and can nest them using parenthesis, e.g. Sr(s, p) or s(up), p(down). The order of the selections does not matter, but it is case sensitive to distinguish p (angular momentum l = 1) from P (phosphorus).

• source (str, optional) – If you used a KPOINTS_OPT file to use a second k-point mesh, you can provide a keyword argument source=”kpoints_opt” to use the k-points defined in that file instead of the one specified in KPOINTS.

Returns

Contains the energies at which the DOS was evaluated aligned to the Fermi energy and the total DOS or the spin-resolved DOS for spin-polarized calculations. If available and a selection is passed, the orbital resolved DOS for the selected orbitals is included.

Return type

dict

Examples

Select the p orbitals of the first atom in the POSCAR file:

>>> calc.dos.read(selection="1(p)")

Select the d orbitals of Mn, Co, and Fe:

>>> calc.dos.read("d(Mn, Co, Fe)")

Select the spin-up contribution of the first three atoms combined

>>> calc.dos.read("up(1:3)")

to_frame(selection=None)¶

Read the data into a pandas DataFrame.

Parameters

• selection (str) –

  A string specifying the projection of the orbitals. There are three distinct possibilities:

  • To specify the atom, you can either use its element name (Si, Al, …) or its index as given in the input file (1, 2, …). For the latter option it is also possible to specify ranges (e.g. 1:4).

  • To select a particular orbital you can give a string (s, px, dxz, …) or select multiple orbitals by their angular momentum (s, p, d, f).

  • For the spin, you have the options up, down, or total.

  You separate multiple selections by commas or whitespace and can nest them using parenthesis, e.g. Sr(s, p) or s(up), p(down). The order of the selections does not matter, but it is case sensitive to distinguish p (angular momentum l = 1) from P (phosphorus).

• source (str, optional) – If you used a KPOINTS_OPT file to use a second k-point mesh, you can provide a keyword argument source=”kpoints_opt” to use the k-points defined in that file instead of the one specified in KPOINTS.

Returns

Contains the energies at which the DOS was evaluated aligned to the Fermi energy and the total DOS or the spin-resolved DOS for spin-polarized calculations. If available and a selection is passed, the orbital resolved DOS for the selected orbitals is included.

Return type

pd.DataFrame

Examples

Select the p orbitals of the first atom in the POSCAR file:

>>> calc.dos.to_frame(selection="1(p)")

Select the d orbitals of Mn, Co, and Fe:

>>> calc.dos.to_frame("d(Mn, Co, Fe)")

Select the spin-up contribution of the first three atoms combined

>>> calc.dos.to_frame("up(1:3)")

to_image(*args, filename=None, **kwargs)¶

Read the data and generate an image writing to the given filename.

The filetype is automatically deduced from the filename; possible are common raster (png, jpg) and vector (svg, pdf) formats. If no filename is provided a default filename is deduced from the name of the class and the picture has png format.

Note that the filename must be a keyword argument, i.e., you explicitly need to write filename=”name_of_file” because the arguments are passed on to the plot() function. Please check the documentation of that function to learn which arguments are allowed.

to_plotly(selection=None)¶

Read the data and generate a plotly figure.

Parameters

• selection (str) –

  A string specifying the projection of the orbitals. There are three distinct possibilities:

  • To specify the atom, you can either use its element name (Si, Al, …) or its index as given in the input file (1, 2, …). For the latter option it is also possible to specify ranges (e.g. 1:4).

  • To select a particular orbital you can give a string (s, px, dxz, …) or select multiple orbitals by their angular momentum (s, p, d, f).

  • For the spin, you have the options up, down, or total.

  You separate multiple selections by commas or whitespace and can nest them using parenthesis, e.g. Sr(s, p) or s(up), p(down). The order of the selections does not matter, but it is case sensitive to distinguish p (angular momentum l = 1) from P (phosphorus).

• source (str, optional) – If you used a KPOINTS_OPT file to use a second k-point mesh, you can provide a keyword argument source=”kpoints_opt” to use the k-points defined in that file instead of the one specified in KPOINTS.

Returns

plotly figure containing the total DOS. If the calculation was spin polarized, the resulting DOS is spin resolved and the spin-down DOS is plotted towards negative values. If a selection the orbital resolved DOS is given for the specified projectors.

Return type

plotly.graph_objects.Figure

Examples

Select the p orbitals of the first atom in the POSCAR file:

>>> calc.dos.plot(selection="1(p)")

Select the d orbitals of Mn, Co, and Fe:

>>> calc.dos.plot("d(Mn, Co, Fe)")

Select the spin-up contribution of the first three atoms combined

>>> calc.dos.plot("up(1:3)")