Dos¶

class py4vasp.data.Dos(data_context, **kwargs)¶

Bases: Refinery, Mixin

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.

Attributes Summary

path	Returns the path from which the output is obtained.

Methods Summary

from_data(raw_data)	Create the instance directly from the raw data.
from_file(file)	Read the quantities from the given file.
from_path([path])	Read the quantities from the given path.
plot(*args, **kwargs)	Wrapper around the to_graph() function.
print()	Print a string representation of this instance.
read(*args, **kwargs)	Convenient wrapper around to_dict.
to_dict([selection])	Read the data into a dictionary.
to_frame([selection])	Read the data into a pandas DataFrame.
to_graph([selection])	Generate a graph of the selected data reading it from the VASP output.
to_image(*args[, filename])	Read the data and generate an image writing to the given filename.
to_plotly(*args, **kwargs)	Convert the graph of this quantity to a plotly figure.

Attributes Documentation

path¶

Returns the path from which the output is obtained.

Methods Documentation

classmethod from_data(raw_data)¶

Create the instance directly from the raw data.

Use this approach when the data is put into the correct format by other means than reading from the VASP output files. A typical use case is to read the data with from_path and then act on it with some postprocessing and pass the results to this method.

Parameters:

raw_data – The raw data required to produce this Refinery.

Return type:

A Refinery instance to handle the passed data.

classmethod from_file(file)¶

Read the quantities 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 io.BufferedReader) – Filename from which the data is extracted. Alternatively, you can open the file yourself and pass the Reader 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 Reader object is passed in which case this is left to the user.

Return type:

Refinery

Notes

VASP produces multiple output files whereas this routine will only link to the single specified file. Prefer from_path routine over this method unless you renamed the VASP output files, because from_path can collate results from multiple files.

classmethod from_path(path=None)¶

Read the quantities from the given path.

The VASP schema determines the particular files accessed. The files will only be accessed when the data is required for a particular postprocessing call.

Parameters:

path (str or pathlib.Path) – Path to the directory with the outputs of the VASP calculation. If not set explicitly the current directory will be used.

Returns:

The returned instance handles opening and closing the files for every function called on it.

Return type:

Refinery

plot(*args, **kwargs)¶

Wrapper around the to_graph() function.

This will merge multiple graphs if you specify different sources with the selection arguments. All arguments are passed to the wrapped function.

print()¶

Print a string representation of this instance.

read(*args, **kwargs)¶

Convenient wrapper around to_dict. Check that function for examples and optional arguments.

to_dict(selection=None)¶

Read the data into a dictionary.

Parameters:

selection (str) –

A string specifying the projection of the orbitals. There are four 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.

• If you used a different k-point mesh choose “kpoints_opt” or “kpoints_wan” to select them instead of the default mesh specified in the KPOINTS file.

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

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.to_dict(selection="1(p)")

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

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

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

>>> calc.dos.to_dict("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 four 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.

• If you used a different k-point mesh choose “kpoints_opt” or “kpoints_wan” to select them instead of the default mesh specified in the KPOINTS file.

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

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_graph(selection=None)¶

Generate a graph of the selected data reading it from the VASP output.

Parameters:

selection (str) –

A string specifying the projection of the orbitals. There are four 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.

• If you used a different k-point mesh choose “kpoints_opt” or “kpoints_wan” to select them instead of the default mesh specified in the KPOINTS file.

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

Returns:

Graph 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 is given the orbital-resolved DOS is given for the specified projectors.

Return type:

Graph

Examples

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

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

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

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

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

>>> calc.dos.to_graph("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 to_graph() function. Please check the documentation of that function to learn which arguments are allowed.

to_plotly(*args, **kwargs)¶

Convert the graph of this quantity to a plotly figure.

The arguments to this function are automatically passed on to the to_graph() function. Please check the documentation of that function to learn which arguments are allowed.