PAOFLOW.gen.fermi_plotter#

fermi-plotter — interactive 3-D Fermi-surface viewer for PAOFLOW BXSF output.

Reads a Fermi-surface BXSF file written by PAOFLOW (FermiSurf_{ispin}.bxsf, produced by PAOFLOW.writers.write2bxsf.write2bxsf()) and renders the Fermi sheets as interactive iso-surfaces with Mayavi. The surfaces are extracted with marching cubes and coloured by the Fermi velocity \(|\nabla_{\mathbf k} E|\). The Mayavi window supports rotation, zoom and pan out of the box.

This module backs the fermi-plotter console script (see [project.scripts] in pyproject.toml).

Usage examples#

Composite image (all bands crossing the Fermi window):

fermi-plotter FermiSurf_0.bxsf

A single band (by its BXSF band label):

fermi-plotter FermiSurf_0.bxsf --band 58

A subset of bands, upsampled 2x for smoother sheets, saved to PNG:

fermi-plotter FermiSurf_0.bxsf --band 57,58 --interp 2 --save fermi.png

Only one spin channel is handled per run; point the tool at the desired FermiSurf_{ispin}.bxsf file directly.

Requires the fermisurface extra (pip install "PAOFLOW[fermisurface]" or pip install mayavi scikit-image).

Classes#

FermiSurfData

Parsed contents of a (possibly multi-band) PAOFLOW BXSF file.

Functions#

read_fermi_bxsf(path)

Read a PAOFLOW Fermi-surface BXSF file (single or multi-band).

fft_upsample(grid, factor)

Fourier zero-padding upsampling of a periodic energy grid.

fermi_velocity_field(energy, recip)

Return the Fermi-velocity magnitude |grad_k E| on the grid.

plot_fermi_surface(data, band_labels[, interp, ...])

Render the selected Fermi sheets with Mayavi.

main([argv])

Console-script entry point for fermi-plotter.

Module Contents#

class PAOFLOW.gen.fermi_plotter.FermiSurfData[source]#

Parsed contents of a (possibly multi-band) PAOFLOW BXSF file.

Variables:

  • fermi_energy (float) – Fermi energy in eV, as written in the BEGIN_INFO block.

  • dims (tuple[int, int, int]) – Grid dimensions (Nx, Ny, Nz) as stored in the file. PAOFLOW writes the periodic wrap-around grid, so Nx = nk1 + 1 etc.

  • recip (np.ndarray, shape (3, 3)) – Reciprocal-lattice (spanning) vectors as stored in the file; row i is the i-th vector (units of \(2\pi/a_{\rm lat}\)).

  • bands (dict[int, np.ndarray]) – Mapping of BXSF band label -> energy grid of shape dims (eV).

fermi_energy: float[source]#
dims: tuple[int, int, int][source]#
recip: numpy.ndarray[source]#
bands: dict[int, numpy.ndarray][source]#
PAOFLOW.gen.fermi_plotter.read_fermi_bxsf(path)[source]#

Read a PAOFLOW Fermi-surface BXSF file (single or multi-band).

Unlike PAOFLOW.pyskeaf.io_bxsf.read_bxsf (which targets single-band, non-periodic SKEAF grids), this reader accepts the multi-band, periodic-wrapped grid that write2bxsf emits.

Parameters:

path (str or Path) – Path to the .bxsf file.

Returns:

Parsed Fermi energy, grid dimensions, reciprocal vectors and per-band energy grids.

Return type:

FermiSurfData

PAOFLOW.gen.fermi_plotter.fft_upsample(grid, factor)[source]#

Fourier zero-padding upsampling of a periodic energy grid.

The PAOFLOW grid is periodic with a duplicated endpoint plane in each direction. This routine strips the wrap plane, upsamples the base (period) grid by factor via Fourier zero-padding (exact for periodic band energies), and re-appends the wrap plane so the result stays closed for marching cubes.

Parameters:

  • grid (np.ndarray, shape (Nx, Ny, Nz)) – Wrap-closed energy grid (N_i = n_i + 1).

  • factor (int) – Integer upsampling factor (>= 1). 1 returns the input.

Returns:

Upsampled, wrap-closed grid of shape (factor*n_x + 1, factor*n_y + 1, factor*n_z + 1) along axes with n_i > 1 (axes of length 1 are left unchanged).

Return type:

np.ndarray

PAOFLOW.gen.fermi_plotter.fermi_velocity_field(energy, recip)[source]#

Return the Fermi-velocity magnitude |grad_k E| on the grid.

Parameters:

  • energy (np.ndarray, shape (Nx, Ny, Nz)) – Wrap-closed energy grid (eV).

  • recip (np.ndarray, shape (3, 3)) – Reciprocal spanning vectors (rows).

Returns:

|grad_k E| at every grid node (eV per reciprocal-length unit).

Return type:

np.ndarray, shape (Nx, Ny, Nz)

PAOFLOW.gen.fermi_plotter.plot_fermi_surface(data, band_labels, interp=1, fermi_shift=0.0, cmap='jet', opacity=1.0, show_bz=True, figsize=(900, 700), save=None)[source]#

Render the selected Fermi sheets with Mayavi.

Parameters:

  • data (FermiSurfData) – Parsed BXSF contents.

  • band_labels (list[int]) – BXSF band labels to render. A single element gives a one-band image; multiple elements give the composite image.

  • interp (int, optional) – Integer Fourier upsampling factor for smoother sheets (default 1).

  • fermi_shift (float, optional) – Energy offset (eV) added to the Fermi level defining the iso-surface.

  • cmap (str, optional) – Mayavi/VTK colormap name for the velocity colouring.

  • opacity (float, optional) – Surface opacity in [0, 1].

  • show_bz (bool, optional) – Draw the reciprocal-cell parallelepiped wireframe.

  • figsize (tuple[int, int], optional) – Render window size in pixels.

  • save (str, optional) – If given, render and save a PNG to this path instead of opening an interactive window. (VTK on macOS has no OSMesa off-screen backend, so this still renders through a normal on-screen window.)

PAOFLOW.gen.fermi_plotter.main(argv=None)[source]#

Console-script entry point for fermi-plotter.