sisl.physics.BandStructure

class sisl.physics.BandStructure(parent, *args, **kwargs)

Bases: BrillouinZone

Create a path in the Brillouin zone for plotting band-structures etc.

Parameters:

  • parent (object or array_like) – An object with associated parent.cell and parent.rcell or an array of floats which may be turned into a Lattice

  • points (array_like of float) – a list of points that are the corners of the path. Define a discontinuity in the points by adding a None in the list.

  • divisions (int or array_like of int) – number of divisions in each segment. If a single integer is passed it is the total number of points on the path (equally separated). If it is an array_like input it must have length one less than point, in this case the total number of points will be sum(divisions) + 1 due to the end-point constraint.

  • names (array_like of str) – the associated names of the points on the Brillouin Zone path

  • jump_dk (float or array_like, optional) – Percentage of self.lineark()[-1] that is used as separation between discontinued jumps in the band-structure. For band-structures with disconnected jumps the lineark and lineartick methods returns a separation between the disconnected points according to this percentage. Default value is 5% of the total distance. Alternatively an array equal to the number of discontinuity jumps may be passed for individual percentages. Keyword only, argument.

Examples

>>> lattice = Lattice(10)
>>> bs = BandStructure(lattice, [[0] * 3, [0.5] * 3], 200)
>>> bs = BandStructure(lattice, [[0] * 3, [0.5] * 3, [1.] * 3], 200)
>>> bs = BandStructure(lattice, [[0] * 3, [0.5] * 3, [1.] * 3], 200, ['Gamma', 'M', 'Gamma'])

A disconnected band structure may be created by having None as the element. Note that the number of names does not contain the empty points (they are simply removed). Such a band-structure may be useful when one is interested in a discontinuous band structure.

>>> bs = BandStructure(lattice, [[0, 0, 0], [0, 0.5, 0], None, [0.5, 0, 0], [0.5, 0.5, 0]], 200)

Methods

copy([parent])

Create a copy of this object, optionally changing the parent

in_primitive(k)

Move the k-point into the primitive point(s) ]-0.5 ; 0.5]

insert_jump(*arrays[, value])

Return a copy of arrays filled with value at indices of discontinuity jumps

iter([ret_weight])

An iterator for the k-points and (possibly) the weights

lineark([ticks])

A 1D array which corresponds to the delta-k values of the path

lineartick()

The tick-marks corresponding to the linear-k values

merge(bzs[, weight_scale, parent])

Merge several BrillouinZone objects into one

param_circle(parent, N_or_dk, kR, normal, origin)

Create a parameterized k-point list where the k-points are generated on a circle around an origin

parametrize(parent, func, N, *args, **kwargs)

Generate a new BrillouinZone object with k-points parameterized via the function func in N separations

set_parent(parent)

Update the parent associated to this object

tocartesian([k])

Transfer a k-point in reduced coordinates to the Cartesian coordinates

tolinear(k[, ret_index, atol])

Convert a k-point into the equivalent linear k-point via the distance

toreduced(k)

Transfer a k-point in Cartesian coordinates to the reduced coordinates

volume([ret_dim, axes])

Calculate the volume of the BrillouinZone, optionally only on some axes axes

write(sile, *args, **kwargs)

Writes k-points to a tableSile.

apply

Loop over all k-points by applying parent methods for all k.

cell

k

A list of all k-points (if available)

plot

Handles all plotting possibilities for a class

rcell

weight

Weight of the k-points in the BrillouinZone object
__init__(parent, *args, **kwargs)[source]
apply

Loop over all k-points by applying parent methods for all k.

This allows potential for running and collecting various computationally heavy methods from a single point on all k-points.

The apply method will dispatch the parent methods through all k-points and passing k as arguments to the parent methods in a straight-forward manner.

For instance to iterate over all eigenvalues of a Hamiltonian

>>> H = Hamiltonian(...)
>>> bz = BrillouinZone(H)
>>> for ik, eigh in enumerate(bz.apply.eigh()):
...    # do something with eigh which corresponds to bz.k[ik]

By default the apply method exposes a set of dispatch methods:

  • apply.iter, the default iterator module

  • apply.average reduced result by averaging (using BrillouinZone.weight as the weight per k-point.

  • apply.sum reduced result without weighing

  • apply.array return a single array with all values; has len equal to number of k-points

  • apply.none, specialized method that is mainly useful when wrapping methods

  • apply.list same as apply.array but using Python list as return value

  • apply.oplist using sisl.oplist allows greater flexibility for mathematical operations element wise

  • apply.datarray if xarray is available one can retrieve an xarray.DataArray instance

Please see Brillouin zone for further examples.

property cell: ndarray
copy(parent=None) → BandStructure

Create a copy of this object, optionally changing the parent

Parameters:
Return type:

BandStructure

static in_primitive(k: numpy.typing.ArrayLike) → ndarray

Move the k-point into the primitive point(s) ]-0.5 ; 0.5]

Parameters:

k (array_like) – k-point(s) to move into the primitive cell

Returns:

all k-points moved into the primitive cell

Return type:

ndarray

insert_jump(*arrays, value=nan)[source]

Return a copy of arrays filled with value at indices of discontinuity jumps

Arrays with value in jumps is easier to plot since those lines will be naturally discontinued. For band structures without discontinuity jumps in the Brillouin zone the arrays will be return as is.

It will insert value along the first dimension matching the length of self. For each discontinuity jump an element will be inserted.

This may be useful for plotting since np.nan gets interpreted as a discontinuity in the graph thus removing connections between the segments.

Parameters:

  • *arrays (array_like) – arrays will get value inserted where there are jumps in the band structure

  • value (optional) – the value to be inserted at the jump points in the data array

Examples

Create a bandrstructure with a discontinuity.

>>> gr = geom.graphene()
>>> bs = BandStructure(gr, [[0, 0, 0], [0.5, 0, 0], None, [0, 0, 0], [0, 0.5, 0]], 4)
>>> data = np.zeros([len(bs), 10])
>>> data_with_jump = bs.insert_jump(data)
>>> assert data_with_jump.shape == (len(bs)+1, 10)
>>> np.all(data_with_jump[2] == np.nan)
True
iter(ret_weight: bool = False)

An iterator for the k-points and (possibly) the weights

Parameters:

ret_weight (bool, optional) – if true, also yield the weight for the respective k-point

Yields:

  • kpt (k-point)

  • weight (weight of k-point, only if ret_weight is true.)

property k: ndarray

A list of all k-points (if available)

lineark(ticks: bool = False)[source]

A 1D array which corresponds to the delta-k values of the path

This is mainly meant for plotting but may be useful for finding out distances in the reciprocal lattice.

Examples

>>> p = BandStructure(...)
>>> eigs = Hamiltonian.eigh(p)
>>> for i in range(len(Hamiltonian)):
...     plt.plot(p.lineark(), eigs[:, i])

>>> p = BandStructure(...)
>>> eigs = Hamiltonian.eigh(p)
>>> lk, kt, kl = p.lineark(True)
>>> plt.xticks(kt, kl)
>>> for i in range(len(Hamiltonian)):
...     plt.plot(lk, eigs[:, i])
Parameters:

ticks (bool) – if True the ticks for the points are also returned

See also

linspace_bz

converts k-points into a linear distance parameterization

Returns:

  • linear_k (numpy.ndarray) – the positions in reciprocal space determined by the distance between points

  • ticks (numpy.ndarray) – linear k-positions of the points, only returned if ticks is True

  • ticklabels (list of str) – labels at ticks, only returned if ticks is True

Parameters:

ticks (bool)

lineartick()[source]

The tick-marks corresponding to the linear-k values

Returns:

the positions in reciprocal space determined by the distance between points

Return type:

ndarray

See also

lineark

Routine used to calculate the tick-marks.

static merge(bzs, weight_scale: Sequence[float] | float = 1.0, parent=None)

Merge several BrillouinZone objects into one

The merging strategy only stores the new list of k-points and weights. Information retained in the merged objects will not be stored.

Parameters:

  • bzs (list-like of BrillouinZone objects) – each element is a BrillouinZone object with bzs[i].k and bzs[i].weight fields.

  • weight_scale (list-like or float) – these are matched item-wise with bzs and applied to. Internally itertools.zip_longest(fillvalue=weight_scale[-1]) will be used to extend for all bzs.

  • parent (object, optional) – Associated parent in the returned object, will default to bzs[0].parent

Returns:

even if all objects are not BrillouinZone objects the returned object will be.

Return type:

BrillouinZone

classmethod param_circle(parent, N_or_dk: int | float, kR: float, normal, origin, loop: bool = False)

Create a parameterized k-point list where the k-points are generated on a circle around an origin

The generated circle is a perfect circle in the reciprocal space (Cartesian coordinates). To generate a perfect circle in units of the reciprocal lattice vectors one can generate the circle for a diagonal supercell with side-length \(2\pi\), see example below.

Parameters:

  • parent (Lattice, or LatticeChild) – the parent object

  • N_or_dk (int) – number of k-points generated using the parameterization (if an integer), otherwise it specifies the discretization length on the circle (in 1/Ang), If the latter case will use less than 2 points a warning will be raised and the number of points increased to 2.

  • kR (float) – radius of the k-point. In 1/Ang

  • normal (array_like of float) – normal vector to determine the circle plane

  • origin (array_like of float) – origin of the circle used to generate the circular parameterization

  • loop (bool) – whether the first and last point are equal

Examples

>>> lattice = Lattice([1, 1, 10, 90, 90, 60])
>>> bz = BrillouinZone.param_circle(lattice, 10, 0.05, [0, 0, 1], [1./3, 2./3, 0])

To generate a circular set of k-points in reduced coordinates (reciprocal

>>> lattice = Lattice([1, 1, 10, 90, 90, 60])
>>> bz = BrillouinZone.param_circle(lattice, 10, 0.05, [0, 0, 1], [1./3, 2./3, 0])
>>> bz_rec = BrillouinZone.param_circle(2*np.pi, 10, 0.05, [0, 0, 1], [1./3, 2./3, 0])
>>> bz.k[:, :] = bz_rec.k[:, :]
Returns:

with the parameterized k-points.

Return type:

BrillouinZone

Parameters:
static parametrize(parent, func, N: Sequence[int] | int, *args, **kwargs) → BrillouinZone

Generate a new BrillouinZone object with k-points parameterized via the function func in N separations

Generator of a parameterized Brillouin zone object that contains a parameterized k-point list.

Parameters:

  • parent (Lattice, or LatticeChild) – the object that the returned object will contain as parent

  • func (callable) –

    method that parameterizes the k-points, must at least accept three arguments, 1. parent: object 2. N: total number of k-points 3. i: current index of the k-point (starting from 0)

    the function must return a k-point in 3 dimensions.

  • N (int or list of int) – number of k-points generated using the parameterization, or a list of integers that will be looped over. In this case arguments N and i in func will be lists accordingly.

  • *args – additional arguments passed directly to func

  • **kwargs – additional keyword arguments passed directly to func

Return type:

BrillouinZone

Examples

Simple linear k-points

>>> def func(sc, N, i):
...    return [i/N, 0, 0]
>>> bz = BrillouinZone.parametrize(1, func, 10)
>>> assert len(bz) == 10
>>> assert np.allclose(bz.k[-1, :], [9./10, 0, 0])

For double looping, say to create your own grid

>>> def func(sc, N, i):
...    return [i[0]/N[0], i[1]/N[1], 0]
>>> bz = BrillouinZone.parametrize(1, func, [10, 5])
>>> assert len(bz) == 50
plot

Handles all plotting possibilities for a class

property rcell: ndarray
set_parent(parent) → None

Update the parent associated to this object

Parameters:

parent (object or array_like) – an object containing cell vectors

Return type:

None

tocartesian(k: npt.ArrayLike | None = None) → np.ndarray

Transfer a k-point in reduced coordinates to the Cartesian coordinates

Parameters:

k (Optional[npt.ArrayLike]) – k-point in reduced coordinates, defaults to this objects k-points.

Returns:

in units of 1/Ang

Return type:

ndarray

tolinear(k, ret_index: bool = False, atol: float = 0.0001)[source]

Convert a k-point into the equivalent linear k-point via the distance

Finds the index of the k-point in self.k that is closests to k. The returned value is then the equivalent index in lineark.

This is very useful for extracting certain points along the band structure.

Parameters:

  • k (array_like) – the k-point(s) to locate in the linear values

  • ret_index (bool) – whether the indices are also returned

  • atol (float) – when the found k-point has a distance (in Cartesian coordinates) is differing by more than tol a warning will be issued. The tolerance is in units 1/Ang.

toreduced(k: numpy.typing.ArrayLike) → ndarray

Transfer a k-point in Cartesian coordinates to the reduced coordinates

Parameters:

k (list of float) – k-point in Cartesian coordinates

Returns:

in units of reciprocal lattice vectors ]-0.5 ; 0.5] (if k is in the primitive cell)

Return type:

ndarray

volume(ret_dim: bool = False, axes: CellAxes | None = None) → float | tuple[float, int]

Calculate the volume of the BrillouinZone, optionally only on some axes axes

This will return the volume of the Brillouin zone, depending on the dimensions of the system. Here the dimensions of the system is determined by how many dimensions have auxilliary supercells that can contribute to Brillouin zone integrals. Therefore the returned value will have differing units depending on dimensionality.

Parameters:

  • ret_dim (bool) – also return the dimensionality of the system

  • axes (Optional[CellAxes]) – estimate the volume using only the directions indexed by this array. The default axes are only the periodic ones (self.parent.pbc.nonzero()[0]). Hence the units might not necessarily be 1/Ang^3.

Returns:

  • vol – the volume of the Brillouin zone. Units are 1/Ang^D with D being the dimensionality. For 0D it will return 0.

  • dimensionality (int) – the dimensionality of the volume

Return type:

Union[float, tuple[float, int]]

property weight: ndarray

Weight of the k-points in the BrillouinZone object

write(sile: sisl.typing.SileLike, *args, **kwargs) → None

Writes k-points to a tableSile.

This allows one to pass a tableSile or a file-name.

Parameters:
Return type:

None