density¶

py4vasp.calculation.density¶

class py4vasp.calculation._density.Density(data_context, **kwargs)¶

This class accesses various densities (charge, magnetization, …) of VASP.

The charge density is one key quantity optimized by VASP. With this class you can extract the final density and visualize it within the structure of the system. For collinear calculations, one can also consider the magnetization density. For noncollinear calculations, the magnetization density has three components. One may also be interested in the kinetic energy density for metaGGA calculations.

is_collinear()¶: Returns whether the density has a collinear magnetization.

is_noncollinear()¶: Returns whether the density has a noncollinear magnetization.

is_nonpolarized()¶: Returns whether the density is not spin polarized.

plot(*args, **kwargs)¶

Wrapper around to_view() method.

This method will visualize the quantity in the structure. Please refer to the to_view() method for a documentation of the allowed arguments.

Returns:: A visualization of the quantity within the crystal structure.
Return type:: View

print()¶: Print a string representation of this instance.

read(*args, **kwargs)¶: Convenient wrapper around to_dict. Check that function for examples and optional arguments.

selections()¶

Returns possible densities VASP can produce along with all available components.

In the dictionary, the key density lists all different densities you can access from the VASP output provided you set the relevant INCAR tags. You can combine any of these with any possible choice from the key component to further specify the particular output you will receive. If you do not specify a density or a component the other routines will default to the electronic charge and the 0-th component.

To nest density and component, please use parentheses, e.g. charge(1, 2) or 3(kinetic_energy).

For convenience, py4vasp accepts the following aliases

electronic charge density: charge, n, charge_density, and electronic_charge_density
kinetic energy density: kinetic_energy, kinetic_energy, and kinetic_energy_density
0th component: 0, unity, sigma_0, and, scalar
1st component: 1, sigma_x, x, and, sigma_1
2nd component: 2, sigma_y, y, and, sigma_2
3rd component: 3, sigma_z, z, and, sigma_3

Returns:: Possible densities and components to pass as selection in other functions on density.
Return type:: dict

Notes

In the special case of collinear calculations, magnetization, mag, and m are another alias for the 3rd component of the charge density.

Examples

>>> calc = py4vasp.Calculation.from_path(".")
>>> calc.density.to_dict("n")
>>> calc.density.plot("magnetization")
Using synonyms and nesting
>>> calc.density.plot("n m(1,2) mag(sigma_z)")

to_contour(selection=None, *, a=None, b=None, c=None, supercell=None, normal=None)¶

Generate a contour plot of the selected component of the density.

You need to specify a plane defined by two of the lattice vectors by selecting a cut along the third one. You must only select a single cut and the value should correspond to the fractional length along this third lattice vector. py4vasp will then create a plane from the other two lattice vectors and generate a contour plot within this plane.

Usually, the first remaining lattice vector is aligned with the x-axis and the second one such that the angle between the vectors is preserved. You can overwrite this choice by defining a normal direction. Then py4vasp will rotate the normal vector of the plane to align with the specified direction. This is particularly useful if the lattice vector you cut is aligned with a Cartesian direction.

Parameters:

selection (str) – Select which component of the density you want to visualize. Please use the selections method to get all available choices.
a (float) – You must select exactly one of these to specify which of the three lattice vectors you want to remove to form a plane. The assigned value represents the fractional length along this lattice vector, so a = 0.3 will remove the first lattice vector and then take the grid points at 30% of the length of the first vector in the b-c plane. The fractional height uses periodic boundary conditions.
b (float) – You must select exactly one of these to specify which of the three lattice vectors you want to remove to form a plane. The assigned value represents the fractional length along this lattice vector, so a = 0.3 will remove the first lattice vector and then take the grid points at 30% of the length of the first vector in the b-c plane. The fractional height uses periodic boundary conditions.
c (float) – You must select exactly one of these to specify which of the three lattice vectors you want to remove to form a plane. The assigned value represents the fractional length along this lattice vector, so a = 0.3 will remove the first lattice vector and then take the grid points at 30% of the length of the first vector in the b-c plane. The fractional height uses periodic boundary conditions.
supercell (int or np.ndarray) – Replicate the contour plot periodically a given number of times. If you provide two different numbers, the resulting cell will be the two remaining lattice vectors multiplied by the specific number.
normal (str or None) – If not set, py4vasp will align the first remaining lattice vector with the x-axis and the second one such that the angle between the lattice vectors is preserved. You can set it to “x”, “y”, or “z”; then py4vasp will rotate the plane in such a way that the normal direction aligns with the specified Cartesian axis. This may look better if the normal direction is close to a Cartesian axis. You may also set it to “auto” so that py4vasp chooses a close Cartesian axis if it can find any.

Returns:

A contour plot in the plane spanned by the 2 remaining lattice vectors.

Return type:

graph

Examples

Cut a plane through the magnetization density at the origin of the third lattice vector.

>>> calc.density.to_contour("3", c=0)

Replicate a plane in the middle of the second lattice vector 2 times in each direction.

>>> calc.density.to_contour(b=0.5, supercell=2)

Take a slice of the kinetic energy density along the first lattice vector and rotate it such that the normal of the plane aligns with the x axis.

>>> calc.density.to_contour("kinetic_energy", a=0.3, normal="x")

to_dict()¶

Read the density into a dictionary.

Parameters:: selection (str) – VASP computes different densities depending on the INCAR settings. With this parameter, you can control which one of them is returned. Please use the selections routine to get a list of all possible choices.
Returns:: Contains the structure information as well as the density represented on a grid in the unit cell.
Return type:: dict

to_ngl(*args, **kwargs)¶

Convert the view to an NGL widget.

This method wraps the to_view() method and converts the resulting View to an NGL widget. The to_view() method documents all the possible arguments of this function.

Returns:: A widget to display the structure and other quantities in the unit cell.
Return type:: NGLWidget

to_numpy()¶

Convert the density to a numpy array.

The number of components is 1 for nonpolarized calculations, 2 for collinear calculations, and 4 for noncollinear calculations. Each component is 3 dimensional according to the grid VASP uses for the FFTs.

Returns:: All components of the selected density.
Return type:: np.ndarray

to_quiver(*, a=None, b=None, c=None, supercell=None, normal=None)¶

Generate a quiver plot of magnetization density.

For a collinear calculation, the magnetization density will be aligned with the y axis of the plane. For noncollinear calculations, the magnetization density is projected into the plane.

Parameters:

a (float) – You must select exactly one of these to specify which of the three lattice vectors you want to remove to form a plane. The assigned value represents the fractional length along this lattice vector, so a = 0.3 will remove the first lattice vector and then take the grid points at 30% of the length of the first vector in the b-c plane. The fractional height uses periodic boundary conditions.
b (float) – You must select exactly one of these to specify which of the three lattice vectors you want to remove to form a plane. The assigned value represents the fractional length along this lattice vector, so a = 0.3 will remove the first lattice vector and then take the grid points at 30% of the length of the first vector in the b-c plane. The fractional height uses periodic boundary conditions.
c (float) – You must select exactly one of these to specify which of the three lattice vectors you want to remove to form a plane. The assigned value represents the fractional length along this lattice vector, so a = 0.3 will remove the first lattice vector and then take the grid points at 30% of the length of the first vector in the b-c plane. The fractional height uses periodic boundary conditions.
supercell (int or np.ndarray) – Replicate the contour plot periodically a given number of times. If you provide two different numbers, the resulting cell will be the two remaining lattice vectors multiplied by the specific number.
normal (str or None) – If not set, py4vasp will align the first remaining lattice vector with the x-axis and the second one such that the angle between the lattice vectors is preserved. You can set it to “x”, “y”, or “z”; then py4vasp will rotate the plane in such a way that the normal direction aligns with the specified Cartesian axis. This may look better if the normal direction is close to a Cartesian axis. You may also set it to “auto” so that py4vasp chooses a close Cartesian axis if it can find any.

Returns:

A quiver plot in the plane spanned by the 2 remaining lattice vectors.

Return type:

graph

Examples

Cut a plane at the origin of the third lattice vector.

>>> calc.density.to_quiver(c=0)

Replicate a plane in the middle of the second lattice vector 2 times in each direction.

>>> calc.density.to_quiver(b=0.5, supercell=2)

Take a slice of the spin components of the kinetic energy density along the first lattice vector and rotate it such that the normal of the plane aligns with the x axis.

>>> calc.density.to_quiver("kinetic_energy", a=0.3, normal="x")

to_view(selection=None, supercell=None, **user_options)¶

Plot the selected density as a 3d isosurface within the structure.

Parameters:

selection (str) – Can be either charge or magnetization, depending on which quantity should be visualized. For a noncollinear calculation, the density has 4 components which can be represented in a 2x2 matrix. Specify the component of the density in terms of the Pauli matrices: sigma_1, sigma_2, sigma_3.
supercell (int or np.ndarray) – If present the data is replicated the specified number of times along each direction.
user_options – Further arguments with keyword that get directly passed on to the visualizer. Most importantly, you can set isolevel to adjust the value at which the isosurface is drawn.

Returns:

Visualize an isosurface of the density within the 3d structure.

Return type:

View

Examples

>>> calc = py4vasp.Calculation.from_path(".")
Plot an isosurface of the electronic charge density
>>> calc.density.plot()
Plot isosurfaces for positive (blue) and negative (red) magnetization
of a spin-polarized calculation (ISPIN=2)
>>> calc.density.plot("m")
Plot the isosurface for the third component of a noncollinear magnetization
>>> calc.density.plot("m(3)")