FermiSurface

class ifermi.surface.FermiSurface(isosurfaces, reciprocal_space, structure)

Bases: MSONable

A FermiSurface object contains isosurfaces and the reciprocal lattice definition.

Variables:

• isosurfaces – A dict containing a list of isosurfaces for each spin channel.

• reciprocal_space – A reciprocal space defining periodic boundary conditions.

• structure – The structure.

all_properties(spins=None, band_index=None, projection_axis=None, norm=False)

Get the properties for all isosurfaces.

Parameters:

• spins (Spin | Collection[Spin] | None) – One or more spin channels to select. Default is all spins available.

• band_index (int | list | dict | None) –

  A choice of band indices (0-based). Valid options are:

  • A single integer, which will select that band index in both spin channels (if both spin channels are present).

  • A list of integers, which will select that set of bands from both spin channels (if both a present).

  • A dictionary of {Spin.up: band_index_1, Spin.down: band_index_2}, where band_index_1 and band_index_2 are either single integers (if one wishes to plot a single band for that particular spin) or a list of integers. Note that the choice of integer and list can be different for different spin channels.

  • None in which case all bands will be selected.

• projection_axis (tuple[int, int, int] | None) – A (3, ) in array of the axis to project the properties onto (vector properties only).

• norm (bool) – Calculate the norm of the properties (vector properties only). Ignored if projection_axis is set.

Return type:

list[ndarray]

Returns:

A list of properties arrays for each isosurface.

all_vertices_faces(spins=None, band_index=None)

Get the vertices and faces for all isosurfaces.

Parameters:

• spins (Spin | Collection[Spin] | None) – One or more spin channels to select. Default is all spins available.

• band_index (int | list | dict | None) –

  A choice of band indices (0-based). Valid options are:

  • A single integer, which will select that band index in both spin channels (if both spin channels are present).

  • A list of integers, which will select that set of bands from both spin channels (if both a present).

  • A dictionary of {Spin.up: band_index_1, Spin.down: band_index_2}, where band_index_1 and band_index_2 are either single integers (if one wishes to plot a single band for that particular spin) or a list of integers. Note that the choice of integer and list can be different for different spin channels.

  • None in which case all bands will be selected.

Return type:

list[tuple[ndarray, ndarray]]

Returns:

A list of (vertices, faces).

property area: float

Total area of all isosurfaces in the Fermi surface in Å^-2.

property area_surfaces: dict[Spin, ndarray]

Area of each isosurface in the Fermi surface in Å^-2.

as_dict()

Get a json-serializable dict representation of FermiSurface.

Return type:

dict

average_properties(norm=False, projection_axis=None)

Average property across the full Fermi surface.

Parameters:

• norm (bool) – Average the norm of the properties (vector properties only).

• projection_axis (tuple[int, int, int] | None) – A (3, ) in array of the axis to project the properties onto (vector properties only).

Return type:

float | ndarray

Returns:

The averaged property.

average_properties_surfaces(norm=False, projection_axis=None)

Average property for each isosurface in the Fermi surface.

Parameters:

• norm (bool) – Average the norm of the properties (vector properties only).

• projection_axis (tuple[int, int, int] | None) – A (3, ) in array of the axis to project the properties onto (vector properties only).

Return type:

dict[Spin, list[float | ndarray]]

Returns:

The averaged property for each surface in each spin channel.

classmethod from_band_structure(band_structure, mu=0.0, wigner_seitz=False, decimate_factor=None, decimate_method='quadric', smooth=False, property_data=None, property_kpoints=None, calculate_dimensionality=False, supercell_dim=(3, 3, 3), trim_to_first_bz=True)

Create a FermiSurface from a pymatgen band structure object.

Parameters:

• band_structure (BandStructure) – A band structure. The k-points must cover the full Brillouin zone (i.e., not just be the irreducible mesh). Use the ifermi.interpolator.FourierInterpolator class to expand the k-points to the full Brillouin zone if required.

• mu (float) – Energy offset from the Fermi energy at which the isosurface is calculated.

• wigner_seitz (bool) – Controls whether the cell is the Wigner-Seitz cell or the reciprocal unit cell parallelepiped.

• decimate_factor (float | None) – If method is “quadric”, and factor is a floating point value then factor is the scaling factor by which to reduce the number of faces. I.e., final # faces = initial # faces * factor. If method is “quadric” but factor is an integer then factor is the target number of final faces. If method is “cluster”, factor is the voxel size in which to cluster points. Default is None (no decimation).

• decimate_method (str) – Algorithm to use for decimation. Options are “quadric” or “cluster”.

• smooth (bool) – If True, will smooth resulting isosurface. Requires PyMCubes. See compute_isosurfaces for more information.

• property_data (dict[Spin, ndarray] | None) – A property to project onto the Fermi surface. It should be given as a dict of {spin: properties}, where properties is numpy array with shape (nbands, nkpoints, …). The number of bands should equal the number of bands in the band structure but the k-point mesh can be different. Must be used in combination with kpoints.

• property_kpoints (ndarray | None) – The k-points on which the data is generated. Must be used in combination with data.

• calculate_dimensionality (bool) – Whether to calculate isosurface dimensionalities.

• supercell_dim (tuple[int, int, int]) – The supercell mesh dimensions.

• trim_to_first_bz (bool) – If true, only includes Fermi surface within one Brillouin zone. If false, include Fermi surface within entire supercell.

Return type:

FermiSurface

Returns:

A Fermi surface.

classmethod from_dict(d)

Return FermiSurface object from dict.

Return type:

FermiSurface

get_fermi_slice(plane_normal, distance=0)

Get a slice through the Fermi surface.

Slice defined by the intersection of a plane with the Fermi surface.

Parameters:

• plane_normal (tuple[int, int, int]) – (3, ) int array of the plane normal in fractional indices.

• distance (float) – The distance from the center of the Brillouin zone (Γ-point).

Returns:

The Fermi slice.

property has_properties: bool

Whether all isosurfaces have face properties.

property n_surfaces: int

Number of isosurfaces in the Fermi surface.

property n_surfaces_per_band: dict[Spin, dict[int, int]]

Get number of surfaces for each band index for each spin channel.

Returned as a dict of {spin: {band_idx: count}}.

property n_surfaces_per_spin: dict[Spin, int]

Get number of surfaces per spin channel.

Returned as a dict of {spin: count}.

property properties_ndim: int

Dimensionality of isosurface properties.

property spins

The spin channels in the Fermi surface.