2D spin-texture

This module can be utilized to visualize the constant energy surface spin textures in a given system. This feature is particularly useful in identifying Rashba and Dresselhaus type spin-splitting effects, analyzing the topology of Fermi-surface, and examining Lifshitz transitions. To plot 2D spin texture, we require a 2D \(k\)-grid centered a certain special \(k\)-point in Brillouin zone near which we want to examine the spin-texture in \(k\)-space (see section example_kmesh_generator regarding generation of 2D \(k\)-mesh).

Usage: To plot \(S_x\) spin component at a constant energy surface \(E = E_{F} + 0.60\,eV\) (spin=1, 2, 3 for \(S_x\), \(S_y\), \(S_z\), respectively):

pyprocar.fermi2D(code='vasp', dirname = 'fermi', st=True, energy=0.60, noarrow=True, spins=[1], )

One could also plot spin texture using arrows instead of a heat map. This can be done by setting the tag: noarrow=False. To set maximum and minimum energy values for color map, one could use vmin and vmax tags.

Translate and Rotate the 2D KPOINT mesh

For any spin-texture in a 2D K-plane, PyProcar usually treats Z-direction as the normal, and makes plot in the X-Y plane. It works fine when we have a 2D k-mesh in (\(k_x\), \(k_y\), 0) plane, but for other 2D k-meshes (e.g. Y-Z or X-Z), it gives us Value Error or Segmentation Fault.

The solution is to rotate the PROCAR by 90 degrees and make the Z-axis perpendicular to the 2D plane. But we should first translate our mesh to a particular K-point (which is mostly the center of the k-mesh) to define the rotation point, and then decide the rotation axis and rotation angle.

To translate the k-mesh:

translate=[2,2,0]

220 is the index of the \(k\)-point in the 2D \(k\)-mesh to define the rotation point (counting starts from 0).

To define the rotation angle and rotation axis:

rotation=[90,0,1,0]

This defines the rotation angle = 90, and Y-axis as the rotation axis. PyProcar always performs the translation operation first and then does the rotation.

Be careful: Now \(S_x\), \(S_y\) and \(S_z\) all will be rotated according to the user’s choice. \(S_y\) will be same as before but \(S_x\) would now be \(S_z\) and \(S_z\) would be \(-S_x\).

Export plot as a matplotlib.pyplot object

PyProcar allows the plot to be exported as a matplotlib.pyplot object. This allows for further processing of the plot through options available in matplotlib. This can be enabled by setting exportplt = True. Usage:

import matplotlib.pyplot as plt
import pyprocar

plt = pyprocar.fermi2D(code='vasp', dirname = 'fermi', exportplt=True)
plt.title('Using matplotlib options')
plt.show()
class pyprocar.scripts.scriptFermi2D.FermiSurface2DMode(value)[source]

An enumeration for defining the modes of 2D Fermi surface representations.

classmethod from_str(mode: str)[source]

Returns the FermiSurface2DMode enum value from a string.

pyprocar.scripts.scriptFermi2D.fermi2D(code: str, dirname: str, mode: str = 'plain', use_cache: bool = False, spin_projection: SpinProjection | str = 'z^2', fermi: float | None = None, fermi_shift: float = 0.0, band_indices: List[List] | None = None, band_colors: List[List] | None = None, spins: List[int] | None = None, atoms: List[int] | None = None, orbitals: List[int] | None = None, energy: float | None = None, k_z_plane: float = 0.0, k_z_plane_tol: float = 0.01, rot_symm=1, translate: List[int] = [0, 0, 0], rotation: List[int] = [0, 0, 0, 1], point_density: int = 10, interpolation: int = 300, linecollection_kwargs: dict | None = None, linestyles: tuple[str, str] = ('solid', 'dashed'), colors: tuple[str, str] | None = None, linewidths: tuple[float, float] = (0.2, 0.2), alphas: tuple[float, float] = (1.0, 1.0), plot_scatter: bool = True, plot_scatter_kwargs: dict | None = None, plot_contours: bool = True, plot_contours_kwargs: dict | None = None, plot_arrows: bool = True, plot_arrows_kwargs: dict | None = None, arrow_scale: float | None = 1.0, show_colorbar: bool = True, cmap: str = 'plasma', norm: Normalize | None = None, use_norm: bool = False, clim: tuple = (None, None), colorbar_kwargs: dict | None = None, colorbar_tick_kwargs: dict | None = None, colorbar_tick_params_kwargs: dict | None = None, colorbar_label_kwargs: dict | None = None, add_legend: bool = False, show: bool = True, savefig: str | None = None, dpi: int | str = 'figure', savefig_kwargs: dict | None = None, xlabel_kwargs: dict | None = None, ylabel_kwargs: dict | None = None, xlim_kwargs: dict | None = None, ylim_kwargs: dict | None = None, x_major_tick_params_kwargs: dict | None = None, y_major_tick_params_kwargs: dict | None = None, x_minor_tick_params_kwargs: dict | None = None, y_minor_tick_params_kwargs: dict | None = None, major_tick_params_kwargs: dict | None = None, minor_tick_params_kwargs: dict | None = None, x_ticks_kwargs: dict | None = None, y_ticks_kwargs: dict | None = None, figsize: tuple = (6, 6), aspect: float | str = 'equal', set_aspect_kwargs: dict | None = None, ax: Axes | None = None, **kwargs)[source]

Plot the 2D Fermi surface in a constant k_z plane.

This function generates 2D Fermi surface plots by slicing the 3D Fermi surface at a specified k_z plane. It supports multiple visualization modes including plain contours, parametric coloring, and spin texture analysis.

Parameters:

  • code (str) – The DFT code used for the calculation. Options include ‘vasp’, ‘qe’, ‘elk’, ‘abinit’, ‘siesta’, ‘lobster’, etc.

  • dirname (str) – The directory path containing the DFT calculation files.

  • mode (str, optional) – The plotting mode. Options are ‘plain’, ‘plain_bands’, ‘parametric’, or ‘spin_texture’, by default ‘plain’

  • use_cache (bool, optional) – Whether to use cached EBS data if available, by default False

  • spin_projection (SpinProjection or str, optional) – The spin projection component for spin texture mode. Options include ‘x’, ‘y’, ‘z’, ‘x^2’, ‘y^2’, ‘z^2’, by default ‘z^2’

  • fermi (float, optional) – The Fermi energy in eV. If None, the Fermi energy from the calculation will be used, by default None

  • fermi_shift (float, optional) – Energy shift to apply to the Fermi level in eV, by default 0.0

  • band_indices (List[List], optional) – List of band indices for each spin channel to include in the plot, by default None (all bands)

  • band_colors (List[List], optional) – List of colors corresponding to each band index for each spin channel, by default None

  • spins (List[int], optional) – List of spin indices to include. For non-collinear calculations, use [0], by default None (all spins)

  • atoms (List[int], optional) – List of atom indices for atomic projections, by default None (all atoms)

  • orbitals (List[int], optional) – List of orbital indices for orbital projections, by default None (all orbitals)

  • energy (float, optional) – The energy level (relative to Fermi) at which to generate the iso-surface. When None, uses 0 (Fermi energy), by default None

  • k_z_plane (float, optional) – The k_z coordinate of the plane to slice for the 2D surface, by default 0.0

  • k_z_plane_tol (float, optional) – Tolerance for selecting k-points near the k_z plane, by default 0.01

  • rot_symm (int, optional) – Rotational symmetry factor to apply around the z-axis, by default 1

  • translate (List[int], optional) – Translation vector [x, y, z] to apply to k-points, by default [0, 0, 0]

  • rotation (List[int], optional) – Rotation parameters [angle, x, y, z] where angle is in degrees and [x, y, z] is the rotation axis, by default [0, 0, 0, 1]

  • point_density (int, optional) – Density of points for spin texture interpolation, by default 10

  • interpolation (int, optional) – Number of interpolation points for generating smooth contours, by default 300

  • linecollection_kwargs (dict, optional) – Additional keyword arguments for matplotlib LineCollection, by default None

  • linestyles (tuple[str, str], optional) – Line styles for different spin channels, by default (‘solid’, ‘dashed’)

  • colors (tuple[str, str], optional) – Colors for different spin channels, by default None

  • linewidths (tuple[float, float], optional) – Line widths for different spin channels, by default (0.2, 0.2)

  • alphas (tuple[float, float], optional) – Alpha values (transparency) for different spin channels, by default (1.0, 1.0)

  • plot_scatter (bool, optional) – Whether to plot scatter points in spin texture mode, by default True

  • plot_scatter_kwargs (dict, optional) – Additional keyword arguments for scatter plot, by default None

  • plot_contours (bool, optional) – Whether to plot contour lines, by default True

  • plot_contours_kwargs (dict, optional) – Additional keyword arguments for contour plots, by default None

  • plot_arrows (bool, optional) – Whether to plot spin direction arrows in spin texture mode, by default True

  • plot_arrows_kwargs (dict, optional) – Additional keyword arguments for arrow plots, by default None

  • arrow_scale (float or None, optional) – Scaling factor for arrow size in spin texture mode, by default 1.0

  • show_colorbar (bool, optional) – Whether to display the colorbar, by default True

  • cmap (str, optional) – Colormap name for the plot, by default ‘plasma’

  • norm (matplotlib.colors.Normalize, optional) – Normalization for the colormap, by default None

  • clim (tuple, optional) – Color limits (vmin, vmax) for the colormap, by default (None, None)

  • colorbar_kwargs (dict, optional) – Additional keyword arguments for colorbar creation, by default None

  • colorbar_tick_kwargs (dict, optional) – Additional keyword arguments for colorbar tick formatting, by default None

  • colorbar_tick_params_kwargs (dict, optional) – Additional keyword arguments for colorbar tick parameters, by default None

  • colorbar_label_kwargs (dict, optional) – Additional keyword arguments for colorbar label formatting, by default None

  • add_legend (bool, optional) – Whether to add a legend to the plot, by default False

  • show (bool, optional) – Whether to display the plot immediately, by default True

  • savefig (str, optional) – Filename to save the figure. If None, the figure is not saved, by default None

  • dpi (int or str, optional) – Resolution for saved figure. Can be integer DPI or ‘figure’, by default ‘figure’

  • savefig_kwargs (dict, optional) – Additional keyword arguments for figure saving, by default None

  • xlabel_kwargs (dict, optional) – Additional keyword arguments for x-axis label formatting, by default None

  • ylabel_kwargs (dict, optional) – Additional keyword arguments for y-axis label formatting, by default None

  • xlim_kwargs (dict, optional) – Additional keyword arguments for x-axis limits, by default None

  • ylim_kwargs (dict, optional) – Additional keyword arguments for y-axis limits, by default None

  • x_major_tick_params_kwargs (dict, optional) – Additional keyword arguments for x-axis major tick parameters, by default None

  • y_major_tick_params_kwargs (dict, optional) – Additional keyword arguments for y-axis major tick parameters, by default None

  • x_minor_tick_params_kwargs (dict, optional) – Additional keyword arguments for x-axis minor tick parameters, by default None

  • y_minor_tick_params_kwargs (dict, optional) – Additional keyword arguments for y-axis minor tick parameters, by default None

  • major_tick_params_kwargs (dict, optional) – Additional keyword arguments for major tick parameters, by default None

  • minor_tick_params_kwargs (dict, optional) – Additional keyword arguments for minor tick parameters, by default None

  • x_ticks_kwargs (dict, optional) – Additional keyword arguments for x-axis tick parameters, by default None

  • y_ticks_kwargs (dict, optional) – Additional keyword arguments for y-axis tick parameters, by default None

  • figsize (tuple, optional) – Figure size as (width, height) in inches, by default (6, 6)

  • aspect (float | str, optional) – Aspect ratio of the plot, by default “equal”

  • set_aspect_kwargs (dict, optional) – Additional keyword arguments for set_aspect, by default None

  • ax (matplotlib.pyplot.Axes, optional) – Existing axes object to plot on. If None, creates new figure, by default None

  • **kwargs – Additional keyword arguments passed to the FermiSurface class

Returns:

FermiSurface or None – Returns the FermiSurface object if show=False, otherwise returns None

Raises:

  • RuntimeError – If the translate option is invalid (not length 1 or 3)

  • ValueError – If an invalid mode is specified

Examples

Basic usage with VASP calculation:

>>> fermi2D(code='vasp', dirname='calculation_dir')

Plot with parametric coloring for specific atoms and orbitals:

>>> fermi2D(code='vasp', dirname='calculation_dir', mode='parametric',
...         atoms=[0, 1], orbitals=[0, 1, 2])

Generate spin texture plot:

>>> fermi2D(code='vasp', dirname='calculation_dir', mode='spin_texture',
...         spin_projection='z', plot_arrows=True)