Band Structure#

class elecboltz.BandStructure(dispersion: str, chemical_potential: float, unit_cell: Sequence[float], band_params: dict = {}, domain_size: Sequence[float] = array([1., 1., 1.]), bz_ratio: float = 1.0, periodic: bool | Sequence[int | bool] = True, axis_names: Sequence[str] | str = ['a', 'b', 'c'], wavevector_names: Sequence[str] | str = ['kx', 'ky', 'kz'], resolution: int | Sequence[int] = 31, n_correct: int = 2, sort_axis: int = None, **kwargs)#

Contains bandstructure information for a given material.

In addition to the dispersion relation and general parameters, this class also contains methods for discretizing the Fermi surface and calculating electronic properties.

Parameters:

  • dispersion (str) – The dispersion relation. Expresses the dispersion relation in terms of symbols in wavevector_names and additional parameters in band_params. It must be parsable and differentiable by sympy. Energy units are milli eV.

  • chemical_potential (float) – The chemical potential in milli eV.

  • unit_cell (Sequence[float]) – The dimensions of the unit cell in angstrom.

  • band_params (dict, optional) – The parameters of the dispersion relation. Energy units are milli eV and distance units are angstrom.

  • domain_size (Sequence[float]) – The ratio of the reciprocal space domain sidelengths to simple cubic unit cell dimensions in reciprocal space. The product of the numbers in this collection must be equal to the number of atoms in the conventional unit cell specified by unit_cell.

  • periodic (bool or int or Sequence[bool] or Sequence[int]) – If bool, whether periodic boundary conditions are applied to all axes or not. If a single int, specifies which single axis is periodic. If a collection, specifies which axes are periodic. If the collection is of integers, the integers specify the periodic axes, e.g. [0, 2] means periodic in x and z axes. If the collection is of booleans, it specifies whether each axis is periodic or not, e.g. [True, False, True] means periodic in x and z axes, but not in y axis.

  • axis_names (str or Sequence[str], optional) – The names of the unit cell axes. Must be parsable by sympy.symbols.

  • wavevector_names (str or Sequence[str], optional) – The names of the wavevector components. Must be parsable by sympy.symbols.

  • resolution (int or Sequence[int], optional) – Controls the resolution of the grids used for discretizing the Fermi surface. If a collection of integers is provided, each element corresponds to the resolution along the respective axis. If a single integer is provided, it is used for all axes.

  • ncorrect (int, optional) – The number of correction steps for improving the accuracy of the discretization of the Fermi surface.

  • sort_axis (int, optional) – The axis along which to sort the points after triangulation. If None, do not sort the points.

dispersion#

The dispersion relation. Updating this will automatically update energy_func and velocity_func.

Type:

str

chemical_potential#

The chemical potential in milli eV.

Type:

float

unit_cell#

The dimensions of the unit cell in angstrom.

Type:

Sequence[float]

domain_size#

The ratio of the reciprocal space domain sidelengths to simple cubic unit cell dimensions in reciprocal space. The product of the numbers in this collection must be equal to the number of atoms in the conventional unit cell specified by unit_cell.

Type:

Sequence[float]

bz_ratio#

The ratio of the volume of the domain in reciprocal space to the volume of the Brillouin zone. This is used to scale the results to the correct values (e.g. the conductivity).

Type:

float

periodic#

The periodic axes.

Type:

Sequence[int]

band_params#

The parameters of the dispersion relation. Energy units are milli eV and distance units are angstrom.

Type:

dict

kpoints#

The discretized k-points on the Fermi surface. Each row corresponds to a k-point in the form [kx, ky, kz].

Type:

(N, 3) numpy.ndarray

kfaces#

The faces of the triangulated surface in k-space. Each row corresponds to a face in the form [i, j, k], where i, j, and k are the indices of the vertices of the face in the kpoints array.

Type:

(F, 3) numpy.ndarray

periodic_projector#

Projects quantities into the periodic k-space, where points that are periodic images of each other are mapped to the same point.

Type:

scipy.sparse.csr_array

resolution#

The resolution of the grids used for approximating the Fermi surface geometry with the marching cubes algorithm.

Type:

int or Sequence[int]

ncorrect#

The number of Newton–Raphson steps applied to correct the triangulated surface after the marching cubes algorithm.

Type:

int

sort_axis#

The axis along which to sort the points after triangulation.

Type:

int or None

axis_names#

The names of the unit cell axes.

Type:

str or Sequence[str]

wavevector_names#

The names of the wavevector components.

Type:

str or Sequence[str]

calculate_electron_density(depth: int = 7) → float#

Calculate the electron density n_e of the material.

Note that the surface needs to be discretized before calling this method. First, the filling fraction is calculated (see calculate_filling_fraction). The electron density is obtained by dividing the filling fraction by the volume of the unit cell in real space.

Parameters:

depth (int, optional) – The depth of the adaptive octree integration in calculate_filling_fraction.

Returns:

The electron density n_e of the material in SI units.

Return type:

float

calculate_filling_fraction(depth: int = 7) → float#

Calculate the filling fraction n of the material.

The filling fraction is calculated by integrating the volume in the reciprocal space having energy bellow the Fermi level (calculated by an adaptive octree integration method), then dividing by the volume of the unit cell in the reciprocal space.

Parameters:

depth (int, optional) – The depth of the adaptive octree integration. Higher values result in more accurate integration, but take exponentially longer to compute.

Returns:

The filling fraction n of the material.

Return type:

float

calculate_mass()#

Calculate the effective mass of the charge carries.

Returns:

The effective mass divided by the rest mass of the electron, m_e.

Return type:

float

discretize()#

Discretize the Fermi surface.

First, the surface is triangulated using the marching cubes algorithm with resolution controlling the resolution of the grid. Next, to improve the accuracy of the isosurface, n_correct steps of the Newton–Raphson root-finding method are applied to the output of marching cubes. Finally, after the surface construction, periodic boundary conditions are applied to “stitch” the open ends of the surface together.

energy_func(kx, ky, kz)#

Calculate the energy at the given k-point.

Parameters:

  • kx (float) – The components of the wavevector in angstrom^-1.

  • ky (float) – The components of the wavevector in angstrom^-1.

  • kz (float) – The components of the wavevector in angstrom^-1.

Returns:

The energy at the given k-point in milli eV.

Return type:

object like kx, ky, kz

velocity_func(kx, ky, kz)#

Calculate the velocity at the given k-point.

Parameters:

  • kx (float) – The components of the wavevector in angstrom^-1.

  • ky (float) – The components of the wavevector in angstrom^-1.

  • kz (float) – The components of the wavevector in angstrom^-1.

Returns:

The velocity vector at the given k-point in m/s.

Return type:

list of 3 objects like kx, ky, kz