potential

py4vasp.calculation.potential¶

(

data_context,
**kwargs

)

The local potential describes the interactions between electrons and ions.

In DFT calculations, the local potential consists of various contributions, each representing different aspects of the electron-electron and electron-ion interactions. The ionic potential arises from the attraction between electrons and the atomic nuclei. The Hartree potential accounts for the repulsion between electrons resulting from the electron density itself. Additionally, the exchange-correlation (xc) potential approximates the effects of electron exchange and correlation. The accuracy of this approximation directly influences the accuracy of the calculated properties.

In VASP, the local potential is defined in real space on the FFT grid. You control which potentials are written with the WRT_POTENTIAL tag. This class provides the methods to read and visualize the potential. If you are interested in the average potential, you may also look at the workfunction.

path

Returns the path from which the output is obtained.

plot

(*args, **kwargs) → View

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

View: A visualization of the quantity within the crystal structure.

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

() → dict

Returns possible alternatives for this particular quantity VASP can produce.

The returned dictionary contains a single item with the name of the quantity mapping to all possible selections. Each of these selection may be passed to other functions of this quantity to select which output of VASP is used. Some quantities provide additional elements which can be passed as selection for other routines.

Returns

dict: The key indicates this quantity and the values possible choices for arguments to other functions of this quantity.

to_contour

(

selection: str = ’total',
a: float = None,
b: float = None,
c: float = None,
normal: str | None = None,
supercell: int | np.ndarray = None

) → Graph

Generate a 2D contour plot of the selected potential on a slice through the cell.

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 = ’total': Specifies which potential to plot. Can be any of the valid kinds (“total”, “ionic”, “xc”, “hartree”). For “total” and “xc” potentials in spin-polarized calculations, you can select “up” or “down” components (e.g., “total_up”). For noncollinear calculations, you can select spin components (“x”, “y”, “z”).
a: float = None: 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 = None: 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 = None: 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.
normal: str | None = 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.
supercell: int | np.ndarray = None: 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.

Returns

Graph: A Graph object containing the contour plot. The plot shows the selected potential component on the specified 2D slice.

Examples

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

>>> calculation.potential.to_contour(c=0)

Plot the Hartree potential in the (100) plane crossing at 0.5 fractional coordinate

>>> calculation.potential.to_contour(selection="hartree", a=0.5)

Plot the sigma_z-component of the xc potential in a 2x2 supercell in the plane defined by the first two lattice vectors.

>>> calculation.potential.to_contour(selection="xc_z", c=0.2, supercell=2)

to_dict

() → dict

Store all available contributions to the potential in a dictionary.

Returns

dict: The dictionary contains the total potential as well as the potential differences between up and down for collinear or the directional potential for noncollinear calculations. If individual contributions to the potential are available, these are returned, too. Structural information is given for reference.

to_ngl

(*args, **kwargs) → NGLWidget

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

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

to_quiver

(

selection: str = ’total',
a: float = None,
b: float = None,
c: float = None,
normal: str | None = None,
supercell: int | np.ndarray = None

) → Graph

Generate a 2D quiver plot of the magnetic part of the potential on a slice.

This method visualizes the vector field of the magnetization potential (difference between spin-up and spin-down potentials for collinear cases, or the vector components for noncollinear cases) as arrows on a 2D slice through the simulation cell.

Parameters

selection: str = ’total': Specifies which magnetic potential to plot. It must be a kind that can have a magnetic component, i.e., “total” or “xc”. Component selection is not allowed for quiver plots as it inherently plots the vector nature of the magnetization.
a: float = None: 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 = None: 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 = None: 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.
normal: str | None = 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.
supercell: int | np.ndarray = None: 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.

Returns

Graph: A Graph object containing the quiver plot. The plot shows arrows representing the magnitude and direction of the magnetic potential in the specified 2D slice.

Examples

Plot the magnetization of the total potential in the a-b plane

>>> calculation.potential.to_quiver(c=0)

Plot the magnetization of the xc potential in the (010) plane crossing at 0.25 fractional coordinate, using a 2x2 supercell.

>>> calculation.potential.to_quiver(selection="xc", b=0.25, supercell=2)

to_vasp_viewer

(*args, **kwargs) → VASPViewerWidget

Convert the view to a VASP Viewer widget.

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

Returns

VASPViewerWidget: A widget to display the structure and other quantities in the unit cell.

to_view

(

selection: str = ’total',
supercell: int | np.ndarray = None,
**user_options

) → View

Plot an isosurface of a selected potential.

Parameters

selection: str = ’total': Select the kind of potential of which you want the isosurface.
supercell: int | np.ndarray = None: 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 (in eV) to adjust the value at which the isosurface is drawn.

Returns

View: A visualization of the potential isosurface within the crystal structure.