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().

Saving and Loading¶

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)