# Reference¶

## Defining k-points¶

This module contains classes to define sets of k-points, for example for a k-point path, or a regular mesh. All k-points are given in reciprocal lattice coordinates.

class bands_inspect.kpoints.KpointsBase[source]

Base class for classes defining sets of k-points.

abstract classmethod from_hdf5(hdf5_handle)

Deserializes the object stored in HDF5 format.

classmethod from_hdf5_file(hdf5_file, *args, **kwargs)

Loads the object from a file in HDF5 format.

Parameters

hdf5_file (str) – Path of the file.

abstract property kpoints_explicit

Array containing all k-points explicitly.

abstract to_hdf5(hdf5_handle)

Serializes the object to HDF5 format, attaching it to the given HDF5 handle (might be a HDF5 File or Dataset).

to_hdf5_file(hdf5_file)

Saves the object to a file, in HDF5 format.

Parameters

hdf5_file (str) – Path of the file.

class bands_inspect.kpoints.KpointsExplicit(kpoints)[source]

Defines an explicit set of k-points.

Parameters

kpoints (list) – List of explicit k-points.

classmethod from_hdf5(hdf5_handle)[source]

Deserializes the object stored in HDF5 format.

classmethod from_hdf5_file(hdf5_file, *args, **kwargs)

Loads the object from a file in HDF5 format.

Parameters

hdf5_file (str) – Path of the file.

property kpoints_explicit

Array containing all k-points explicitly.

to_hdf5(hdf5_handle)[source]

Serializes the object to HDF5 format, attaching it to the given HDF5 handle (might be a HDF5 File or Dataset).

to_hdf5_file(hdf5_file)

Saves the object to a file, in HDF5 format.

Parameters

hdf5_file (str) – Path of the file.

class bands_inspect.kpoints.KpointsMesh(mesh, offset=None)[source]

Defines k-points on a regular mesh.

Parameters
• mesh (list) – Defines the grid size (number of different k-point values) for each dimension.

• offset (list) – Offset added to the k-point values. If nothing is given, the grid is aligned at the $$\Gamma$$ - point.

classmethod from_hdf5(hdf5_handle)[source]

Deserializes the object stored in HDF5 format.

classmethod from_hdf5_file(hdf5_file, *args, **kwargs)

Loads the object from a file in HDF5 format.

Parameters

hdf5_file (str) – Path of the file.

property kpoints_explicit

Array containing all k-points explicitly.

to_hdf5(hdf5_handle)[source]

Serializes the object to HDF5 format, attaching it to the given HDF5 handle (might be a HDF5 File or Dataset).

to_hdf5_file(hdf5_file)

Saves the object to a file, in HDF5 format.

Parameters

hdf5_file (str) – Path of the file.

class bands_inspect.kpoints.KpointsPath(*, paths, special_points=mappingproxy({}), kpoint_distance=0.001, unit_cell='auto')[source]

Defines a k-point path.

Parameters
• paths (list) – List of paths. Each path is a list of special points.

• special_points (dict) – Mapping of special k-points. The key is the identifier of the special k-point, and the value is its position in reduced coordinates.

• kpoint_distance (float) – Approximate distance between two neighbouring k-points along the path.

• unit_cell (numpy.ndarray) – Unit cell of the material. The basis vectors are given as rows in a matrix.

classmethod from_hdf5(hdf5_handle)[source]

Deserializes the object stored in HDF5 format.

classmethod from_hdf5_file(hdf5_file, *args, **kwargs)

Loads the object from a file in HDF5 format.

Parameters

hdf5_file (str) – Path of the file.

property kpoints_explicit

Array containing all k-points explicitly.

to_hdf5(hdf5_handle)[source]

Serializes the object to HDF5 format, attaching it to the given HDF5 handle (might be a HDF5 File or Dataset).

to_hdf5_file(hdf5_file)

Saves the object to a file, in HDF5 format.

Parameters

hdf5_file (str) – Path of the file.

## Eigenvalue Data¶

Defines the data container for eigenvalue data (bandstructures).

class bands_inspect.eigenvals.EigenvalsData(*, kpoints, eigenvals)[source]

Data container for the eigenvalues at a given set of k-points. The eigenvalues are automatically sorted by value.

Parameters
• kpoints (list) – List of k-points where the eigenvalues are given.

• eigenvals (2D array) – Eigenvalues at each k-point. The outer axis corresponds to the different k-points, and the inner axis corresponds to the different eigenvalues at a given k-point.

classmethod from_eigenval_function(*, kpoints, eigenval_function, listable=False)[source]

Create an instance using a function that calculates the eigenvalues.

Parameters
• kpoints (KpointsBase) – k-points for which the eigenvalues are to be calculated.

• eigenval_function – Function which calculates the eigenvalues.

• listable (bool) – Flag showing whether the function can handle a list of k-points (True) or only single k-points (False).

classmethod from_hdf5(hdf5_handle)[source]

Deserializes the object stored in HDF5 format.

classmethod from_hdf5_file(hdf5_file, *args, **kwargs)

Loads the object from a file in HDF5 format.

Parameters

hdf5_file (str) – Path of the file.

shift(value)[source]

Returns an instance with eigenvalues shifted by the given value.

Parameters

value (float) – The value by which the eigenvalues are shifted.

slice_bands(band_idx)[source]

Returns a new instance which contains only the bands given in the index.

Parameters

band_idx (list) – Indices for the bands in the new instance.

to_hdf5(hdf5_handle)[source]

Serializes the object to HDF5 format, attaching it to the given HDF5 handle (might be a HDF5 File or Dataset).

to_hdf5_file(hdf5_file)

Saves the object to a file, in HDF5 format.

Parameters

hdf5_file (str) – Path of the file.

## Plotting¶

Defines functions to plot bandstructures.

bands_inspect.plot.eigenvals(eigenvals, *, ax=None, ylim=None, e_fermi=0.0, vertex_labels=True, energy_labels=True, plot_options=mappingproxy({'color': 'C0', 'lw': 0.8}))[source]

Plot the bandstructure of a given EigenvalsData object.

## Difference¶

Defines functions to compare two bandstructures by calculating their difference, with different averaging and weighting methods.

bands_inspect.compare.difference.calculate(eigenvals1, eigenvals2, *, avg_func=<function average>, weight_eigenval=<function ones_like>, symmetric_eigenval_weights=True, weight_kpoint=<function <lambda>>)[source]

Calculate the difference between two bandstructures.

Parameters
• eigenvals1 (EigenvalsData) – The first set of eigenvalues.

• eigenvals2 (EigenvalsData) – The second set of eigenvalues.

• avg_func – Function which is used to average the difference between the two sets of eigenvalues.

• weight_eigenval – A function which takes the eigenvalues as input, and returns the corresponding weights.

• symmetric_eigenval_weights (bool) – Determines whether both sets of eigenvalues are used to calculate weights, or just the first one.

• weight_kpoint – A function which takes the k-points as input, and returns the corresponding weights.

bands_inspect.compare.difference.energy_window(lower, upper)[source]

Creates an eigenvalue weighting function that only takes into account eigenvalues in a certain energy window.

Parameters
• lower (float) – Lower bound of the energy window.

• upper (float) – Upper bound of the energy window.

## Alignment¶

Defines a function to align two bandstructures in such a way that their difference is minimized.

bands_inspect.compare.align.calculate(eigenvals1, eigenvals2, *, symmetric_shift=False, **kwargs)[source]

Shift the two sets of eigenvalues such that their difference is minimized.

Parameters
• eigenvals1 (EigenvalsData) – The first set of eigenvalues.

• eigenvals2 (EigenvalsData) – The second set of eigenvalues.

• symmetric_shift (bool) – If True, the two sets of eigenvalues are shifted by equal and opposite values. Otherwise, only the second set of eigenvalues is shifted.

• kwargs (dict) – Keyword arguments passed on to difference.calculate().

This module contains functions to save and load objects, using the HDF5 format.

bands_inspect.io.from_hdf5(hdf5_handle)[source]

Deserializes the given HDF5 handle into an object.

Parameters

hdf5_handle (h5py.File or h5py.Group.) – HDF5 location where the serialized object is stored.

bands_inspect.io.from_hdf5_file(hdf5_file)[source]

Alias for from_hdf5_file().

bands_inspect.io.load(hdf5_file)

Alias for from_hdf5_file().

bands_inspect.io.save(obj, hdf5_file)

Save TBmodels objects to a HDF5 file. Compatible with all types registered through fsc.hdf5_io.

bands_inspect.io.to_hdf5(obj, hdf5_handle)[source]

Serializes a given object to HDF5 format.

Parameters
• obj – Object to serialize.

• hdf5_handle (h5py.File or h5py.Group.) – HDF5 location where the serialized object gets stored.

bands_inspect.io.to_hdf5_file(obj, hdf5_file)[source]

Save TBmodels objects to a HDF5 file. Compatible with all types registered through fsc.hdf5_io.

## Command line interface¶

### bands-inspect¶

bands-inspect [OPTIONS] COMMAND [ARGS]...


#### align¶

Align two bandstructures.

bands-inspect align [OPTIONS]


Options

-i, --input-files <input_files>
-o, --output-files <output_files>
--energy-window <energy_window>

#### difference¶

Calculate the difference between two bandstructures.

bands-inspect difference [OPTIONS] EIGENVAL_FILES...


Options

--energy-window <energy_window>

Arguments

EIGENVAL_FILES

Required argument(s)

#### plot-bands¶

Plot one or more bandstructures which share the same set of k-points.

bands-inspect plot-bands [OPTIONS] EIGENVALS_FILES...


Options

-o, --output <output>

Output file for the plot.

Arguments

EIGENVALS_FILES

Required argument(s)

#### slice-bands¶

Modify a bandstructure by selecting/re-arranging specific bands.

bands-inspect slice-bands [OPTIONS] [SLICE_IDX]...


Options

-i, --input <input>

File containing the input eigenvalues (in HDF5 format).

-o, --output <output>

Arguments

SLICE_IDX

Optional argument(s)