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 SuperCell
points (array_like of float) – a list of points that are the corners of the path
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 thelineark
andlineartick
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
>>> sc = SuperCell(10) >>> bs = BandStructure(sc, [[0] * 3, [0.5] * 3], 200) >>> bs = BandStructure(sc, [[0] * 3, [0.5] * 3, [1.] * 3], 200) >>> bs = BandStructure(sc, [[0] * 3, [0.5] * 3, [1.] * 3], 200, ['Gamma', 'M', 'Gamma'])
A disconnected band structure may be created by either having a point of 0 length, or None. 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 not interested in a fully connected band structure.
>>> bs = BandStructure(sc, [[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
The tick-marks corresponding to the linear-k values
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 separationsset_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, tol])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, periodic])Calculate the volume of the full Brillouin zone of the parent
write
(sile, *args, **kwargs)Writes k-points to a
tableSile
.Loop over all k-points by applying parent methods for all k.
A list of all k-points (if available)
Weight of the k-points in the
BrillouinZone
object- 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 passingk
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 wiseapply.datarray if
xarray
is available one can retrieve anxarray.DataArray
instance
Please see Brillouin zone for further examples.
- property cell
- copy(parent=None)[source]
Create a copy of this object, optionally changing the parent
- Parameters
parent (optional) – change the parent
- static in_primitive(k)
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
- 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=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
A list of all k-points (if available)
- lineark(ticks=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, optional) – 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
- 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
See also
lineark
Routine used to calculate the tick-marks.
- static param_circle(parent, N_or_dk, kR, normal, origin, loop=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 (SuperCell, or SuperCellChild) – 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 4 points a warning will be raised and the number of points increased to 4.
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, optional) – whether the first and last point are equal
Examples
>>> sc = SuperCell([1, 1, 10, 90, 90, 60]) >>> bz = BrillouinZone.param_circle(sc, 10, 0.05, [0, 0, 1], [1./3, 2./3, 0])
To generate a circular set of k-points in reduced coordinates (reciprocal
>>> sc = SuperCell([1, 1, 10, 90, 90, 60]) >>> bz = BrillouinZone.param_circle(sc, 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
- static parametrize(parent, func, N, *args, **kwargs)
Generate a new
BrillouinZone
object with k-points parameterized via the function func in N separationsGenerator of a parameterized Brillouin zone object that contains a parameterized k-point list.
- Parameters
parent (SuperCell, or SuperCellChild) – 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
andi
in func will be lists accordingly.*args – additional arguments passed directly to func
**kwargs – additional keyword arguments passed directly to func
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
- set_parent(parent)
Update the parent associated to this object
- Parameters
parent (object or array_like) – an object containing cell vectors
- tocartesian(k)
Transfer a k-point in reduced coordinates to the Cartesian coordinates
- Parameters
- Returns
in units of 1/Ang
- Return type
- tolinear(k, ret_index=False, tol=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 inlineark
.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, optional) – whether the indices are also returned
tol (float, optional) – 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)
Transfer a k-point in Cartesian coordinates to the reduced coordinates
- Parameters
- Returns
in units of reciprocal lattice vectors ]-0.5 ; 0.5] (if k is in the primitive cell)
- Return type
- volume(ret_dim=False, periodic=None)
Calculate the volume of the full Brillouin zone of the parent
This will return the volume 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
- Returns
vol – the volume of the Brillouin zone. Units are Ang^D with D being the dimensionality. For 0D it will return 0.
dimensionality (int) – the dimensionality of the volume
- property weight
Weight of the k-points in the
BrillouinZone
object