pyprocar.core.FermiSurface

class pyprocar.core.FermiSurface(kpoints, bands, spd, figsize: tuple = (6, 6), ax: Axes | None = None, **kwargs)[source]

A class for plotting and analyzing 2D Fermi surfaces.

This class provides comprehensive functionality for visualizing 2D Fermi surfaces from electronic band structure calculations. It supports plotting Fermi surface contours, spin texture analysis, and various customization options for scientific visualization. The class handles interpolation of k-point data, contour generation, and multiple plotting modes including line segments, scatter plots, and vector fields.

Parameters:

  • kpoints (np.ndarray) – Array of k-points in Cartesian coordinates with shape (n_kpoints, 3). These should be the k-points from the electronic structure calculation.

  • bands (np.ndarray) – Array of band energies with shape (n_kpoints, n_bands, n_spins). The Fermi energy should already be subtracted from these values.

  • spd (np.ndarray) – Array of spin-projected density with shape (n_kpoints, n_bands, n_spins, n_orbitals, n_atoms). Contains the orbital and atomic projections for each k-point and band.

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

  • ax (matplotlib.axes.Axes or None, optional) – Matplotlib axes object to plot on. If None, a new figure and axes will be created, by default None.

  • **kwargs – Additional keyword arguments passed to matplotlib functions.

Variables:

  • fig (matplotlib.figure.Figure) – The matplotlib figure object.

  • ax (matplotlib.axes.Axes) – The matplotlib axes object.

  • handles (list) – List of matplotlib handles for plotted elements.

  • kpoints (np.ndarray) – The k-points array.

  • bands (np.ndarray) – The band energies array.

  • spd (np.ndarray) – The spin-projected density array.

  • energy (float or None) – The energy level for Fermi surface analysis.

  • useful_bands_by_spins (list or None) – List of band indices that cross the specified energy for each spin.

  • x_limits (tuple) – The x-axis limits for plotting.

  • y_limits (tuple) – The y-axis limits for plotting.

  • clim (tuple) – The color limits for color mapping.

Examples

>>> import numpy as np
>>> import matplotlib.pyplot as plt
>>> # Create sample data
>>> kpoints = np.random.rand(100, 3)
>>> bands = np.random.rand(100, 10, 1) - 0.5  # Centered around 0
>>> spd = np.random.rand(100, 10, 1, 4, 1)
>>>
>>> # Initialize FermiSurface
>>> fs = FermiSurface(kpoints, bands, spd)
>>>
>>> # Find bands crossing the Fermi level
>>> fs.find_energy(0.0)
>>>
>>> # Generate and plot contours
>>> contour_data = fs.generate_contours()
>>> fs.plot_band_spin_contour_line_segments(contour_data)
>>>
>>> # Customize the plot
>>> fs.set_xlabel('$k_x$ (Å$^{-1}$)')
>>> fs.set_ylabel('$k_y$ (Å$^{-1}$)')
>>> fs.show()

Notes

The class assumes that the input band energies have the Fermi energy already subtracted, so that the Fermi level corresponds to energy = 0. The k-points should be in Cartesian coordinates and ready for plotting.

For spin texture analysis, additional spin arrays (sx, sy, sz) are required and should be passed to the appropriate spin texture methods.

Methods

FermiSurface.__init__(kpoints, bands, spd[, ...])

Initialize the FermiSurface object.

FermiSurface.add_legend(**kwargs)

Add a legend to the plot.

FermiSurface.find_energy(energy)

A method to find bands which are near a given energy

FermiSurface.generate_band_colors(bands[, ...])

Generate colors for each band using a colormap.

FermiSurface.generate_contours([...])

Generate 2D Fermi surface contours for selected bands.

FermiSurface.generate_spin_texture_contours(sx, ...)

This method generates the spin texture contours

FermiSurface.get_colorbar()

Get the colorbar object.

FermiSurface.plot_band_spin_contour_line_segments(...)

Plot contour line segments for multiple bands and spins.

FermiSurface.plot_contour_line_segments(...)

Plot contour line segments from contour data.

FermiSurface.plot_spin_texture_arrows(...[, ...])

Plot spin texture as arrows (vectors) on Fermi surface contours.

FermiSurface.plot_spin_texture_contours(...)

Plot spin texture contours from spin texture data.

FermiSurface.plot_spin_texture_scatter(...)

Plot spin texture as scatter points on Fermi surface contours.

FermiSurface.savefig(savefig[, dpi])

Save the figure to a file.

FermiSurface.select_bands([band_indices])

Select specific bands for plotting based on band indices.

FermiSurface.set_aspect([aspect])

Set the aspect ratio of the plot.

FermiSurface.set_colorbar_label([label])

Set the label for the colorbar.

FermiSurface.set_colorbar_tick_params(**kwargs)

Set the tick parameters for the colorbar.

FermiSurface.set_colorbar_ticks([n_ticks, ...])

Set the tick positions and labels for the colorbar.

FermiSurface.set_scalar_mappable([norm, ...])

FermiSurface.set_tick_params([axis, which, ...])

Set the tick parameters for the axes.

FermiSurface.set_xlabel([xlabel])

Set the x-axis label.

FermiSurface.set_xlim([xlimits])

Set the x-axis limits.

FermiSurface.set_xticks([n_ticks, ...])

Set the tick positions and labels for the colorbar.

FermiSurface.set_ylabel([ylabel])

Set the y-axis label.

FermiSurface.set_ylim([ylimits])

Set the y-axis limits.

FermiSurface.set_yticks([n_ticks, ...])

Set the tick positions and labels for the colorbar.

FermiSurface.show(**kwargs)

Display the plot.

FermiSurface.show_colorbar([label, n_ticks, ...])

Add a colorbar to the plot.