# ifermi package¶

## ifermi.analysis module¶

Isosurface and isoline analysis functions.

ifermi.analysis.average_properties(vertices, faces, properties, norm=False)[source]

Average property across an isosurface.

Parameters
Return type
Returns

The averaged property.

ifermi.analysis.connected_images(fractional_vertices, tol=1e-05)[source]

Find the images a set of vertices is connected to.

Note: This function expects the vertices to only belong to a single connected mesh, and the vertices should cover a 3x3x3 supercell, where the coordinates from -0.5 to 0.5 indicate the center image.

Parameters
• fractional_vertices (ndarray) – A (n, 3) float array of the vertices in the isosurface in fractional coordinates.

• tol – A tolerance for evaluating whether two vertices are equivalent.

Return type
Returns

A (n, 3) int array of the images across which the mesh is connected periodically.

ifermi.analysis.connected_subsurfaces(vertices, faces)[source]

Find connected sub-surfaces (those that share edges).

Parameters
Return type
Returns

A list of of (vertices, faces) for each sub-surface.

ifermi.analysis.equivalent_surfaces(surfaces_vertices, tol=1e-05)[source]

Note: This function expects the vertices of each surface to only belong to a single connected mesh, and the vertices should cover a 3x3x3 supercell, where the coordinates from -0.5 to 0.5 indicate the center image.

Parameters
• surfaces_vertices (List[ndarray]) – A (m, ) list of (n, 3) float arrays containing the vertices for each surface, in fractional coordinates.

• tol – A tolerance for evaluating whether two vertices are equivalent.

Return type

ndarray

Returns

A (m, ) int array that maps each each surface in the original surface array to its equivalent.

ifermi.analysis.equivalent_vertices(vertices, tol=1e-05)[source]

Find vertices that are equivalent (closer than a tolerance).

Note that the algorithm used is effectively recursive. If vertex a is within the tolerance of b, and b is within the tolerance of c, even if a and c and not within the tolerance, a, b, and c will be considered equivalent.

Parameters
Return type

ndarray

Returns

(n, ) int array that maps each each vertex in the original vertex array to its equivalent.

ifermi.analysis.isosurface_area(vertices, faces)[source]

Calculate the area of an isosurface.

Parameters
Return type

float

Returns

The area of the isosurface, in Å^-2.

ifermi.analysis.isosurface_dimensionality(fractional_vertices, faces)[source]

Calculate isosurface properties a single isosurface (fully connected).

The vertices must cover a 3x3x3 supercell and must not have been trimmed to fit inside the reciprocal lattice.

Note: This function expects the vertices to only belong to a single connected mesh, and the vertices should cover a 3x3x3 supercell, where the coordinates from -0.5 to 0.5 indicate the center image.

Parameters
• fractional_vertices (ndarray) – A (n, 3) float array of the vertices in the isosurface in fractional coordinates.

• faces (ndarray) – A (m, 3) int array of the faces of the isosurface.

Return type
Returns

The dimensionality and (n, 3) int array orientation of the isosurface.

ifermi.analysis.line_orientation(images)[source]

Get the orientation (direction vector) from a list of rank 1 connected images.

Parameters

images (List[Tuple[int, int, int]]) – (n, 3) int array of the images.

Return type
Returns

The orientation vector as a (3, ) int array.

ifermi.analysis.longest_simple_paths(vertices, edges)[source]

Find the shortest paths that go through all vertices.

The lines are broken up into the connected sublines. Note this function is only designed to work with connected sublines that are either simple cycles or chains with no branches.

Parameters
Return type
Returns

A list of (k, ) int arrays (one for each connected subline) specifying the path.

ifermi.analysis.plane_orientation(images)[source]

Get the orientation (surface normal) from a list of rank 2 connected images.

Parameters

images (List[Tuple[int, int, int]]) – (n, 3) int array of the images.

Return type
Returns

The surface normal as a (3, ) int array.

ifermi.analysis.sample_line_uniform(segments, spacing)[source]

Sample line segments to a consistent density.

Note: the segments must be ordered so that they are adjacent.

Parameters
Return type

ndarray

Returns

A (m, ) int array containing the indices of uniformly spaced segments.

ifermi.analysis.sample_surface_uniform(vertices, faces, grid_size)[source]

Sample isosurface faces uniformly.

The algorithm works by:

1. Splitting the mesh into a uniform grid with block sizes determined by grid_size.

2. For each cell in the grid, finds whether the center of any faces falls within the cell.

3. If multiple face centers fall within the cell, it picks the closest one to the center of the cell. If no face centers fall within the cell then the cell is ignored.

4. Returns the indices of all the faces that have been selected.

This algorithm is not well optimised for small grid sizes.

Parameters
Return type

ndarray

Returns

A (k, ) int array containing the indices of uniformly spaced faces.

## ifermi.brillouin_zone module¶

Brillouin zone and slice geometries.

class ifermi.brillouin_zone.ReciprocalCell(reciprocal_lattice, vertices, faces, centers, normals)[source]

Bases: monty.json.MSONable

A parallelepiped reciprocal lattice cell.

reciprocal_lattice

A (3, 3) float array of the reciprocal lattice vectors.

vertices

A (n, 3) float array of the vertices of the Brillouin zone edges.

faces

A (m, 3) int array of the faces of the Brillouin zone.

centers

A (m, 3) float array of the face centers.

normals

A (m, 3) float array of the face normal.

property edges

A (n, 2) int array defining the cell edges.

Return type

ndarray

classmethod from_structure(structure)[source]

Initialise the reciprocal cell from a structure.

Parameters

structure (Structure) – A structure.

Return type

ReciprocalCell

Returns

The reciprocal cell.

get_reciprocal_slice(plane_normal, distance=0)[source]

Get a reciprocal slice through the Brillouin zone.

Reciprocal slice defined by the intersection of a plane with the lattice.

Parameters
Return type

ReciprocalSlice

Returns

The reciprocal slice.

property lines

A (n, 2, 3) float array defining the cell boundaries.

Return type

ndarray

class ifermi.brillouin_zone.ReciprocalSlice(reciprocal_space, vertices, transformation)[source]

Bases: monty.json.MSONable

A slice along a pane in reciprocal space.

reciprocal_space

The reciprocal space that the slice belongs to.

vertices

A (n, 2) float array of the vertices defining the intersection of the slice with the Brillouin zone.

transformation

(n, 4, 4) float array of the transformation that maps points in the 3D Brillouin zone to points on the 2D slice.

property edges

A (n, 2) int array defining the cell edges.

Return type

ndarray

property lines

A (n, 2, 2) float array defining the cell boundaries.

Return type

ndarray

class ifermi.brillouin_zone.WignerSeitzCell(reciprocal_lattice, vertices, faces, centers, normals)[source]

WignerSeitz cell of the reciprocal lattice.

reciprocal_lattice

A (3, 3) float array of the reciprocal lattice vectors.

vertices

A (n, 3) float array of the vertices of the Brillouin zone edges.

faces

A (m, 3) int array of the faces of the Brillouin zone.

centers

A (m, 3) float array of the face centers.

normals

A (m, 3) float array of the face normal.

classmethod from_structure(structure)[source]

Initialise the Wigner–Seitz cell from a structure.

Parameters

structure (Structure) – A structure.

Return type

WignerSeitzCell

Returns

An instance of the cell.

## ifermi.interpolate module¶

Tools for Fourier and linear interpolation.

class ifermi.interpolate.FourierInterpolator(band_structure, magmom=None, mommat=None)[source]

Bases: object

Class to perform Fourier interpolation of electronic band structures.

Interpolation is performed using BoltzTraP2.

Parameters
interpolate_bands(interpolation_factor=5, return_velocities=False, nworkers=- 1)[source]

Get an interpolated pymatgen band structure.

Note, the interpolation mesh is determined using by interpolate_factor option in the FourierInterpolator constructor.

The degree of parallelization is controlled by the nworkers option.

Parameters
• interpolation_factor (float) – The factor by which the band structure will be interpolated.

• return_velocities (bool) – Whether to return the group velocities.

• nworkers (int) – The number of processors used to perform the interpolation. If set to -1, the number of workers will be set to the number of CPU cores.

Returns

The interpolated electronic structure. If return_velocities is True, the group velocities will also be returned as a dict of {Spin: velocities} where velocities is a numpy array with the shape (nbands, nkpoints, 3) and has units of m/s.

class ifermi.interpolate.LinearInterpolator(kpoints, data)[source]

Bases: object

Class to perform linear interpolation of periodic properties.

Parameters
• kpoints (ndarray) – The k-points in fractional coordinates as a numpy array. with the shape (nkpoints, 3). Note, the k-points must cover the full Brillouin zone, not just the irreducible part.

• data (Dict[Spin, ndarray]) – The data to interpolate. Should be given for spin up and spin down bands. If the system is not spin polarized then only spin up should be set. The data for each spin channel should be a numpy array with the shape (nbands, nkpoints, …). The values to interpolate can be scalar or multidimensional.

interpolate(spin, bands, kpoints)[source]

Get the interpolated data for a spin channel and series of bands and k-points.

Parameters
Returns

A list of interpolated values.

ifermi.interpolate.trim_bandstructure(energy_cutoff, band_structure)[source]

Trim the number of bands in a band structure object based on a cutoff.

Parameters
• energy_cutoff (float) – An energy cutoff within which to keep the bands. If the system is metallic then the bands to keep will fall within +/- the cutoff around the Fermi level. If the system has a band gap, the bands from the VBM - energy_cutoff to CBM + energy_cutoff will be kept.

• band_structure (BandStructure) – A band structure.

Return type

BandStructure

Returns

A trimmed band structure.

## ifermi.kpoints module¶

k-point manipulation functions.

ifermi.kpoints.get_kpoint_mesh_dim(kpoints, tol=1e-05)[source]

Get the k-point mesh dimensions.

Parameters
Return type
Returns

A (3, ) int array of the k-point mesh dimensions.

ifermi.kpoints.get_kpoint_spacing(kpoints)[source]

Get the spacing between fractional k-points.

Parameters

kpoints (ndarray) – A (n, 3) float array of the k-points in fractional coordinates.

Return type

ndarray

Returns

A (3, ) float array of the spacing along each reciprocal lattice direction.

ifermi.kpoints.kpoints_from_bandstructure(bandstructure, cartesian=False)[source]

Extract the k-points from a band structure.

Parameters
Return type

ndarray

Returns

A (n, 3) float array of the k-points.

ifermi.kpoints.kpoints_to_first_bz(kpoints, tol=1e-05)[source]

Translate fractional k-points to the first Brillouin zone.

I.e. all k-points will have fractional coordinates:

-0.5 <= fractional coordinates < 0.5

Parameters
Return type

ndarray

Returns

A (n, 3) float array of the translated k-points.

ifermi.kpoints.sort_boltztrap_to_spglib(kpoints)[source]

Get an index array that sorts the k-points from BoltzTraP2 to the order from spglib.

Parameters

kpoints (ndarray) – A (n, 3) float array of the k-points in fractional coordinates.

Return type

ndarray

Returns

A (n, ) int array of the sort order.

## ifermi.plot module¶

Tools to plot FermiSurface and FermiSlice objects.

class ifermi.plot.FermiSlicePlotter(fermi_slice, symprec=0.001)[source]

Bases: object

Class to plot 2D isolines through a FermiSurface.

Parameters
get_plot(ax=None, spin=None, colors=None, color_properties=True, vector_properties=False, projection_axis=None, scale_linewidth=False, vector_spacing=0.2, cmin=None, cmax=None, vnorm=None, hide_slice=False, hide_labels=False, hide_cell=False, arrow_pivot='tail', slice_kwargs=None, cbar_kwargs=None, quiver_kwargs=None, bz_kwargs=None, sym_pt_kwargs=None, sym_label_kwargs=None)[source]

Plot the Fermi slice.

Parameters
• ax (Optional[Any]) – Matplotlib axes object on which to plot.

• spin (Optional[Spin]) – Which spin channel to plot. By default plot both spin channels if available.

• The color specification for the iso-surfaces. Valid options are:

• A single color to use for all Fermi isolines, specified as a tuple of rgb values from 0 to 1. E.g., red would be (1, 0, 0).

• A list of colors, specified as above.

• A dictionary of {Spin.up: color1, Spin.down: color2}, where the colors are specified as above.

• A string specifying which matplotlib colormap to use. See https://matplotlib.org/tutorials/colors/colormaps.html for more information.

• None, in which case the default colors will be used.

• color_properties (Union[str, bool]) – Whether to use the properties to color the Fermi isolines. If the properties is a vector then the norm of the properties will be used. Note, this will only take effect if the Fermi slice has properties. If set to True, the viridis colormap will be used. Alternative colormaps can be selected by setting color_properties to a matplotlib colormap name. This setting will override the colors option. For vector properties, the arrows are colored according to the norm of the properties by default. If used in combination with the projection_axis option, the color will be determined by the dot product of the properties with the projection axis.

• vector_properties (Union[str, bool]) – Whether to plot arrows for vector properties. Note, this will only take effect if the Fermi slice has vector properties. If set to True, the viridis colormap will be used. Alternative colormaps can be selected by setting vector_properties to a matplotlib colormap name. By default, the arrows are colored according to the norm of the properties. If used in combination with the projection_axis option, the color will be determined by the dot product of the properties with the projection axis.

• projection_axis (Optional[Tuple[int, int, int]]) – Projection axis that can be used to calculate the color of vector properties. If None, the norm of the properties will be used, otherwise the color will be determined by the dot product of the properties with the projection axis. Only has an effect when used with the vector_properties option.

• scale_linewidth (Union[bool, float]) – Scale the linewidth by the absolute value of the segment properties. Can be true, false or a number. If a number, then this will be used as the max linewidth for scaling.

• vector_spacing (float) – The rough spacing between arrows. Uses a custom algorithm for resampling the Fermi surface to ensure that arrows are not too close together. Only has an effect when used with the vector_properties option.

• cmin (Optional[float]) – Minimum intensity for normalising properties colors (including vector colors). Only has an effect when used with color_properties or vector_properties options.

• cmax (Optional[float]) – Maximum intensity for normalising properties colors (including vector colors). Only has an effect when used with color_properties or vector_properties options.

• vnorm (Optional[float]) – The value by which to normalize the vector lengths. For example, spin properties should typically have a norm of 1 whereas group velocity properties can have larger or smaller norms depending on the structure. By changing this number, the size of the vectors will be scaled. Note that the properties of two materials can only be compared quantitatively if a fixed values is used for both plots. Only has an effect when used with the vector_properties option.

• hide_slice (bool) – Whether to hide the Fermi surface. Only recommended in combination with the vector_properties option.

• hide_labels (bool) – Whether to show the high-symmetry k-point labels.

• hide_cell (bool) – Whether to show the reciprocal cell boundary.

• arrow_pivot (str) – The part of the arrow that is anchored to the X, Y grid. The arrow rotates about this point, options are: tail, middle, tip.

• slice_kwargs (Optional[Dict[str, Any]]) – Optional arguments that are passed to LineCollection and are used to style the iso slice.

• cbar_kwargs (Optional[Dict[str, Any]]) – Optional arguments that are passed to fig.colorbar.

• quiver_kwargs (Optional[Dict[str, Any]]) – Optional arguments that are passed to ax.quiver and are used to style the arrows.

• bz_kwargs (Optional[Dict[str, Any]]) – Optional arguments that passed to LineCollection and used to style the Brillouin zone boundary.

• sym_pt_kwargs (Optional[Dict[str, Any]]) – Optional arguments that are passed to ax.scatter and are used to style the high-symmetry k-point symbols.

• sym_label_kwargs (Optional[Dict[str, Any]]) – Optional arguments that are passed to ax.text and are used to style the high-symmetry k-point labels.

Returns

matplotlib pyplot object.

static get_symmetry_points(fermi_slice, symprec=0.001)[source]

Get the high symmetry k-points and labels for the Fermi slice.

Parameters
Return type
Returns

The high symmetry k-points and labels for points that lie on the slice.

class ifermi.plot.FermiSurfacePlotter(fermi_surface, symprec=0.001)[source]

Bases: object

Class to plot a FermiSurface.

Parameters
get_plot(plot_type='plotly', spin=None, colors=None, azimuth=45.0, elevation=35.0, color_properties=True, vector_properties=False, projection_axis=None, vector_spacing=0.2, cmin=None, cmax=None, vnorm=None, hide_surface=False, hide_labels=False, hide_cell=False, **plot_kwargs)[source]

Plot the Fermi surface.

Parameters
• plot_type (str) – Method used for plotting. Valid options are: “matplotlib”, “plotly”, “mayavi”, “crystal_toolkit”.

• spin (Optional[Spin]) – Which spin channel to plot. By default plot both spin channels if available.

• azimuth (float) – The azimuth of the viewpoint in degrees. i.e. the angle subtended by the position vector on a sphere projected on to the x-y plane.

• elevation (float) – The zenith angle of the viewpoint in degrees, i.e. the angle subtended by the position vector and the z-axis.

• The color specification for the iso-surfaces. Valid options are:

• A single color to use for all Fermi surfaces, specified as a tuple of rgb values from 0 to 1. E.g., red would be (1, 0, 0).

• A list of colors, specified as above.

• A dictionary of {Spin.up: color1, Spin.down: color2}, where the colors are specified as above.

• A string specifying which matplotlib colormap to use. See https://matplotlib.org/tutorials/colors/colormaps.html for more information.

• None, in which case the default colors will be used.

• color_properties (Union[str, bool]) – Whether to use the properties to color the Fermi surface. If the properties is a vector then the norm of the properties will be used. Note, this will only take effect if the Fermi surface has properties. If set to True, the viridis colormap will be used. Alternative colormaps can be selected by setting color_properties to a matplotlib colormap name. This setting will override the colors option. For vector properties, the arrows are colored according to the norm of the properties by default. If used in combination with the projection_axis option, the color will be determined by the dot product of the properties with the projection axis.

• vector_properties (Union[str, bool]) – Whether to plot arrows for vector properties. Note, this will only take effect if the Fermi surface has vector properties. If set to True, the viridis colormap will be used. Alternative colormaps can be selected by setting vector_properties to a matplotlib colormap name. By default, the arrows are colored according to the norm of the properties. If used in combination with the projection_axis option, the color will be determined by the dot product of the properties with the projection axis.

• projection_axis (Optional[Tuple[int, int, int]]) – Projection axis that can be used to calculate the color of vector properties. If None, the norm of the properties will be used, otherwise the color will be determined by the dot product of the properties with the projection axis. Only has an effect when used with the vector_properties option.

• vector_spacing (float) – The rough spacing between arrows. Uses a custom algorithm for resampling the Fermi surface to ensure that arrows are not too close together. Only has an effect when used with the vector_properties option.

• cmin (Optional[float]) – Minimum intensity for normalising properties colors (including vector colors). Only has an effect when used with color_properties or vector_properties options.

• cmax (Optional[float]) – Maximum intensity for normalising properties colors (including vector colors). Only has an effect when used with color_properties or vector_properties options.

• vnorm (Optional[float]) – The value by which to normalize the vector lengths. For example, spin properties should typically have a norm of 1 whereas group velocity properties can have larger or smaller norms depending on the structure. By changing this number, the size of the vectors will be scaled. Note that the properties of two materials can only be compared quantitatively if a fixed values is used for both plots. Only has an effect when used with the vector_properties option.

• hide_surface (bool) – Whether to hide the Fermi surface. Only recommended in combination with the vector_properties option.

• hide_labels (bool) – Whether to show the high-symmetry k-point labels.

• hide_cell (bool) – Whether to show the reciprocal cell boundary.

• **plot_kwargs – Other keyword arguments supported by the individual plotting methods.

static get_symmetry_points(fermi_surface, symprec=0.001)[source]

Get the high symmetry k-points and labels for the Fermi surface.

Parameters
Return type
Returns

The high symmetry k-points and labels.

ifermi.plot.cmap_to_mayavi(colormap)[source]

Convert a matplotlib colormap to mayavi format.

Parameters

colormap (Colormap) – A matplotlib colormap object.

Return type

ndarray

Returns

The equivalent mayavi colormap, as a (255, 4) numpy array.

ifermi.plot.cmap_to_plotly(colormap)[source]

Convert a matplotlib colormap to plotly colorscale format.

Parameters

colormap (Colormap) – A matplotlib colormap object.

Return type
Returns

The equivalent plotly colorscale.

ifermi.plot.get_face_arrows(fermi_surface, spins, vector_spacing, vnorm, projection_axis)[source]

Get face arrows from vector properties.

Parameters
• fermi_surface (FermiSurface) – The fermi surface containing the isosurfaces and properties.

• spins (List[Spin]) – Spin channels from which to extract arrows.

• vector_spacing (float) – The rough spacing between arrows. Uses a custom algorithm for resampling the Fermi surface to ensure that arrows are not too close together.

• vnorm (Optional[float]) – The value by which to normalize the vector lengths. For example, spin properties should typically have a norm of 1 whereas group velocity properties can have larger or smaller norms depending on the structure. By changing this number, the size of the vectors will be scaled. Note that the properties of two materials can only be compared quantitatively if a fixed values is used for both plots.

• projection_axis (Optional[Tuple[int, int, int]]) – Projection axis that can be used to calculate the color of vector projections. If None, the norm of the properties will be used, otherwise the color will be determined by the dot product of the properties with the projection axis.

Return type
Returns

The arrows, as a list of (starts, stops, intensities) for each face. The starts and stops are numpy arrays with the shape (narrows, 3) and intensities is a numpy array with the shape (narrows, ). The intensities are used to color the arrows during plotting.

ifermi.plot.get_isosurface_colors(colors, fermi_object, spins)[source]

Get colors for each Fermi surface.

Parameters
Return type
Returns

The colors as a list of tuples, where each color is specified as the rgb values from 0 to 1. E.g., red would be (1, 0, 0).

ifermi.plot.get_plot_type(plot)[source]

Get the plot type.

Parameters

plot (Any) – A plot object from FermiSurfacePlotter.get_plot(). Supports matplotlib pyplot objects, plotly figure objects, and mlab figure objects.

Return type

str

Returns

The plot type. Current options are “matplotlib”, “mayavi”, and “plotly”.

ifermi.plot.get_segment_arrows(fermi_slice, spins, vector_spacing, vnorm, projection_axis)[source]

Get segment arrows from vector properties.

Parameters
• fermi_slice (FermiSlice) – The Fermi slice containing the isolines and properties.

• spins (Collection[Spin]) – Spin channels from which to extract arrows.

• vector_spacing (float) – The rough spacing between arrows. Uses a custom algorithm for resampling the Fermi slic to ensure that arrows are not too close together.

• vnorm (Optional[float]) – The value by which to normalize the vector lengths. For example, spin properties should typically have a norm of 1 whereas group velocity properties can have larger or smaller norms depending on the structure. By changing this number, the size of the vectors will be scaled. Note that the properties of two materials can only be compared quantitatively if a fixed values is used for both plots.

• projection_axis (Optional[Tuple[int, int, int]]) – Projection axis that can be used to calculate the color of vector projects. If None, the norm of the properties will be used, otherwise the color will be determined by the dot product of the properties with the properties axis.

Return type
Returns

The arrows, as a list of (starts, stops, intensities) for each face. The starts and stops are numpy arrays with the shape (narrows, 3) and intensities is a numpy array with the shape (narrows, ). The intensities are used to color the arrows during plotting.

ifermi.plot.plotly_arrow(start, stop, color, line_kwargs=None, cone_kwargs=None)[source]

Create an arrow object.

Parameters
Return type
Returns

The arrow, formed by a line and cone.

ifermi.plot.rgb_to_plotly(color)[source]

Get a plotly formatted color from rgb values.

Parameters

color (Tuple[float, float, float]) – The color in rgb format as a tuple of three floats from 0 to 1.

Return type

str

Returns

The plotly formatted color.

ifermi.plot.save_plot(plot, filename, scale=4)[source]

Save a plot to file.

Parameters
ifermi.plot.show_plot(plot)[source]

Display a plot.

Parameters

plot (Any) – A plot object from FermiSurfacePlotter.get_plot(). Supports matplotlib pyplot objects, plotly figure objects, and mlab figure objects.

## ifermi.slice module¶

Tools to generate Isolines and Fermi slices.

class ifermi.slice.FermiSlice(isolines, reciprocal_slice, structure)[source]

Bases: monty.json.MSONable

A FermiSlice object is a 2D slice through a Fermi surface.

isolines

A dict containing a list of isolines for each spin channel.

reciprocal_space

A reciprocal slice defining the intersection of the slice with the Brillouin zone edges.

structure

The structure.

all_lines(spins=None)[source]

Get the segments for all isolines.

Parameters

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

Return type
Returns

A list of segments arrays.

all_properties(spins=None, projection_axis=None, norm=False)[source]

Get the properties for all isolines.

Parameters
Return type
Returns

A list of properties arrays for each isosurface.

as_dict()[source]

Get a json-serializable dict representation of a FermiSlice.

Return type

dict

classmethod from_dict(d)[source]

Return FermiSlice object from a dict.

Return type

FermiSlice

classmethod from_fermi_surface(fermi_surface, plane_normal, distance=0)[source]

Get a slice through the Fermi surface.

The slice is defined by the intersection of a plane with the Fermi surface.

Parameters
Return type

FermiSlice

Returns

The Fermi slice.

property has_properties

Whether all isolines have segment properties.

Return type

bool

property n_lines

Number of isolines in the Fermi slice.

Return type

int

property n_lines_per_band

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

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

Return type
property n_lines_per_spin

Get number of lines per spin channel.

Returned as a dict of {spin: count}.

Return type
property properties_ndim

Dimensionality of isoline properties.

Return type

int

property spins

The spin channels in the Fermi slice.

Return type
class ifermi.slice.Isoline(segments, band_idx, properties=None)[source]

Bases: monty.json.MSONable

An isoline object contains line segments mesh and line properties.

segments

A (n, 2, 2) float array of the line segments..

band_idx

The band index to which the slice belongs.

properties

An optional (n, …) float array containing segment properties as scalars or vectors.

property has_properties

Whether the isoline has properties.

Return type

float

property properties_ndim

Dimensionality of face properties.

Return type

int

property properties_norms

(m, ) norm of isoline properties.

Return type

ndarray

sample_uniform(spacing)[source]

Sample line segments uniformly.

See the docstring for ifermi.analysis.sample_line_uniform for more details.

Parameters

spacing (float) – The spacing in Å^-1.

Return type

ndarray

Returns

A (n, ) int array containing the indices of uniformly spaced segments.

scalar_projection(axis)[source]

Get scalar projection of properties onto axis.

Parameters

axis (Tuple[int, int, int]) – A (3, ) int array of the axis to project onto.

Return type

ndarray

ifermi.slice.interpolate_segments(segments, properties, max_spacing)[source]

Resample a series of line segments to a consistent density.

Note: the segments must be ordered so that they are adjacent.

Parameters
• segments (ndarray) – A (n, 2, 2) float array of the line segments.

• properties (ndarray) – A (n, …) float array of the segment properties.

• max_spacing (float) – The desired spacing after interpolation. Note, the spacing may be slightly smaller than this value.

Returns

The interpolated segments and properties.

Return type

(segments, properties)

ifermi.slice.process_lines(segments, face_idxs)[source]

Process segments and face_idxs from mesh_multiplane.

The key issue is that the segments from mesh_multiplane do not correspond to individual lines, nor are they sorted in a continuous order. Instead they are just a list of randomly ordered segments. This causes trouble later on when trying to interpolate the lines or add equally spaced arrows.

The goal of this function is to identify the separate paths in the segments (a path is a collection of segments that are connected together), and return these segments in the order that they are connected. By looping through each segment, you will be proceeding along the line in a certain direction.

Because the original segments may contain multiple paths, a list of segments and their corresponding face indices are returned.

Lastly, note that there is no guarantee that all of the original segments will be used in the processed segments. This is because some of the original segments are very small and will be filtered out.

Parameters
Return type
Returns

A list of (segments, faces) for each path.

## ifermi.surface module¶

Tools to generate isosurfaces and Fermi surfaces.

class ifermi.surface.FermiSurface(isosurfaces, reciprocal_space, structure)[source]

Bases: monty.json.MSONable

A FermiSurface object contains isosurfaces and the reciprocal lattice definition.

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, projection_axis=None, norm=False)[source]

Get the properties for all isosurfaces.

Parameters
Return type
Returns

A list of properties arrays for each isosurface.

all_vertices_faces(spins=None)[source]

Get the vertices and faces for all isosurfaces.

Parameters

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

Return type
Returns

A list of (vertices, faces).

property area

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

Return type

float

property area_surfaces

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

Return type
as_dict()[source]

Get a json-serializable dict representation of FermiSurface.

Return type

dict

average_properties(norm=False, projection_axis=None)[source]

Average property across the full Fermi surface.

Parameters
Return type
Returns

The averaged property.

average_properties_surfaces(norm=False, projection_axis=None)[source]

Average property for each isosurface in the Fermi surface.

Parameters
Return type
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)[source]

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 (Optional[float]) – 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 (Optional[Dict[Spin, ndarray]]) – 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 (Optional[ndarray]) – The k-points on which the data is generated. Must be used in combination with data.

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

Return type

FermiSurface

Returns

A Fermi surface.

classmethod from_dict(d)[source]

Return FermiSurface object from dict.

Return type

FermiSurface

get_fermi_slice(plane_normal, distance=0)[source]

Get a slice through the Fermi surface.

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

Parameters
Return type

FermiSlice

Returns

The Fermi slice.

property has_properties

Whether all isosurfaces have face properties.

Return type

bool

property n_surfaces

Number of isosurfaces in the Fermi surface.

Return type

int

property n_surfaces_per_band

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

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

Return type
property n_surfaces_per_spin

Get number of surfaces per spin channel.

Returned as a dict of {spin: count}.

Return type
property properties_ndim

Dimensionality of isosurface properties.

Return type

int

property spins

The spin channels in the Fermi surface.

class ifermi.surface.Isosurface(vertices, faces, band_idx, properties=None, dimensionality=None, orientation=None)[source]

Bases: monty.json.MSONable

An isosurface object contains a triangular mesh and surface properties.

vertices

A (n, 3) float array of the vertices in the isosurface.

faces

A (m, 3) int array of the faces of the isosurface.

band_idx

The band index to which the surface belongs.

properties

An optional (m, …) float array containing face properties as scalars or vectors.

dimensionality

The dimensionality of the surface.

orientation

The orientation of the surface (for 1D and 2D surfaces only).

property area

Area of the isosurface in Å-2.

Return type

float

average_properties(norm=False, projection_axis=None)[source]

Average property across isosurface.

Parameters
Return type
Returns

The averaged property.

property has_properties

Whether the surface has properties.

Return type

float

property properties_ndim

Dimensionality of face properties.

Return type

int

property properties_norms

(m, ) norm of isosurface properties.

Return type

ndarray

sample_uniform(grid_size)[source]

Sample mesh faces uniformly.

See the docstring for ifermi.analysis.sample_surface_uniform for more details.

Parameters

grid_size (float) – The grid size in Å^-1.

Return type

ndarray

Returns

A (n, ) int array containing the indices of uniformly spaced faces.

scalar_projection(axis)[source]

Get scalar projection of properties onto axis.

Parameters

axis (Tuple[int, int, int]) – A (3, ) int array of the axis to project onto.

Return type

ndarray

Returns

(m, ) float array of scalar projection of properties.

ifermi.surface.compute_isosurfaces(bands, kpoints, fermi_level, reciprocal_space, decimate_factor=None, decimate_method='quadric', smooth=False, calculate_dimensionality=False, property_interpolator=None)[source]

Compute the isosurfaces at a particular energy level.

Parameters
• bands (Dict[Spin, ndarray]) – The band energies, given as a dictionary of {spin: energies}, where energies has the shape (nbands, nkpoints).

• kpoints (ndarray) – The k-points in fractional coordinates.

• fermi_level (float) – The energy at which to calculate the Fermi surface.

• reciprocal_space (ReciprocalCell) – The reciprocal space representation.

• decimate_factor (Optional[float]) – 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. Smoothing algorithm will use constrained smoothing algorithm to preserve fine details if input dimension is lower than (500, 500, 500), otherwise will apply a Gaussian filter.

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

• property_interpolator (Optional[LinearInterpolator]) – An interpolator class for interpolating properties onto the surface. If None, no properties will be calculated.

Return type
Returns

A dictionary containing a list of isosurfaces for each spin channel.

ifermi.surface.decimate_mesh(vertices, faces, factor, method='quadric')[source]

Decimate mesh to reduce the number of triangles and vertices.

The open3d package is required for decimation.

Parameters
• vertices (ndarray) – A (n, 3) float array of the vertices in the isosurface.

• faces (ndarray) – A (m, 3) int array of the faces of the isosurface.

• factor (Union[int, float]) – 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.

• method – Algorithm to use for decimation. Options are “quadric” or “cluster”.

Returns

(vertices, faces) of the decimated mesh.

ifermi.surface.expand_bands(bands, fractional_kpoints, supercell_dim=3, 3, 3, center=0, 0, 0)[source]

Expand the band energies and k-points with periodic boundary conditions.

Parameters
Return type
Returns

(energies, kpoints) The expanded band energies and k-points.

ifermi.surface.face_properties(interpolator, vertices, faces, band_idx, spin, reciprocal_lattice)[source]

Interpolate properties data onto the Fermi surfaces.

Parameters
Return type

ndarray

Returns

A (m, …) float array of the interpolated properties at the center of each face in the isosurface.

ifermi.surface.trim_surface(reciprocal_cell, vertices, faces)[source]

Trim the surface to remove parts outside the cell boundaries.

Will add new triangles at the boundary edges as necessary to produce a smooth surface.

Parameters
Return type
Returns

(vertices, faces) of the trimmed surface.