BandStructure¶

class sisl.physics.brillouinzone.BandStructure(parent, point, division, name=None)[source]¶

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

Parameters

parentobject or array_like: An object with associated parentcell and parent.rcell or an array of floats which may be turned into a SuperCell
pointarray_like of float: a list of points that are the corners of the path
divisionint 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.
namearray_like of str: the associated names of the points on the Brillouin Zone path

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'])

Attributes

`cell`
`k`	A list of all k-points (if available)
`rcell`
`weight`	Weight of the k-points in the `BrillouinZone` object

Methods

`__init__`(self, parent, point, division[, name])	Initialize self.
`asarray`(self)	Return self with `numpy.ndarray` returned quantities
`asaverage`(self)	Return self with k-averaged quantities
`aslist`(self)	Return self with list returned quantities
`asnone`(self)	Return self with None, this may be done for instance when wrapping the function calls.
`assum`(self)	Return self with summed quantities
`asyield`(self)	Return self with yielded quantities
`call`(self, func, \args, \\*kwargs)	Call the function func and run as though the function has been called
`copy`(self)	Create a copy of this object
`in_primitive`(k)	Move the k-point into the primitive point(s) ]-0.5 ; 0.5]
`iter`(self[, ret_weight])	An iterator for the k-points and (possibly) the weights
`lineark`(self[, ticks])	A 1D array which corresponds to the delta-k values of the path
`lineartick`(self)	The tick-marks corresponding to the linear-k values
`param_circle`(sc, N_or_dk, kR, normal, origo)	Create a parameterized k-point list where the k-points are generated on a circle around an origo
`parametrize`(sc, func, N, \args, \\*kwargs)	Generate a new `BrillouinZone` object with k-points parameterized via the function func in N separations
`set_parent`(self, parent)	Update the parent associated to this object
`tocartesian`(self, k)	Transfer a k-point in reduced coordinates to the Cartesian coordinates
`toreduced`(self, k)	Transfer a k-point in Cartesian coordinates to the reduced coordinates
`write`(self, sile, \args, \\*kwargs)	Writes k-points to a `tableSile`.

asarray(self)¶

Return self with numpy.ndarray returned quantities

This forces the __call__ routine to return a single array.

See also

asyield: all output returned through an iterator
asaverage: take the average (with k-weights) of the Brillouin zone
assum: return the sum of values in the Brillouin zone
aslist: all output returned as a Python list

Notes

All invocations of sub-methods are added these keyword-only arguments:

etabool, optional: if true a progress-bar is created, default false.
wrapcallable, optional: a function that accepts the output of the given routine and post-process it. Defaults to lambda x: x.

Examples

>>> obj = BrillouinZone(...)
>>> obj.asarray().eigh(eta=True)

To compute multiple things in one go one should use wrappers to contain the calculation

>>> E = np.linspace(-2, 2, 100)
>>> dist = get_distribution('gaussian', smearing=0.1)
>>> def wrap(es, parent, k, weight):
...    DOS = es.DOS(E, distribution=dist)
...    PDOS = es.PDOS(E, distribution=dist)
...    occ = es.occupation()
...    spin_moment = (es.spin_moment(E, distribution=dist) * occ.reshape(-1, 1)).sum(0)
...    return oplist([DOS, PDOS, spin_moment])
>>> bz = BrillouinZone(hamiltonian)
>>> DOS, PDOS, spin_moment = bz.asaverage().eigenstate(wrap=wrap)

asaverage(self)¶

Return self with k-averaged quantities

This forces the __call__ routine to return a single k-averaged value.

See also

asarray: all output as a single array
asyield: all output returned through an iterator
assum: return the sum of values in the Brillouin zone
aslist: all output returned as a Python list

Notes

All invocations of sub-methods are added these keyword-only arguments:

etabool, optional: if true a progress-bar is created, default false.
wrapcallable, optional: a function that accepts the output of the given routine and post-process it. Defaults to lambda x: x.

Examples

>>> obj = BrillouinZone(Hamiltonian)
>>> obj.asaverage().DOS(np.linspace(-2, 2, 100))

>>> obj = BrillouinZone(Hamiltonian)
>>> obj.asaverage()
>>> obj.DOS(np.linspace(-2, 2, 100))
>>> obj.PDOS(np.linspace(-2, 2, 100), eta=True)

>>> obj = BrillouinZone(Hamiltonian)
>>> obj.asaverage()
>>> E = np.linspace(-2, 2, 100)
>>> def wrap(es):
...    return es.DOS(E), es.PDOS(E)
>>> DOS, PDOS = obj.eigenstate(wrap=wrap)

aslist(self)¶

Return self with list returned quantities

This forces the __call__ routine to return a list with returned values.

See also

asarray: all output as a single array
asyield: all output returned through an iterator
assum: return the sum of values in the Brillouin zone
asaverage: take the average (with k-weights) of the Brillouin zone

Notes

All invocations of sub-methods are added these keyword-only arguments:

etabool, optional: if true a progress-bar is created, default false.
wrapcallable, optional: a function that accepts the output of the given routine and post-process it. Defaults to lambda x: x.

Examples

>>> obj = BrillouinZone(...)
>>> def first_ten(es):
...    return es.sub(range(10))
>>> obj.aslist().eigenstate(eta=True, wrap=first_ten)

asnone(self)¶

Return self with None, this may be done for instance when wrapping the function calls.

This forces the __call__ routine to return None. This usage is mainly intended when creating custom wrap function calls.

See also

asyield: all output returned through an iterator
asaverage: take the average (with k-weights) of the Brillouin zone
assum: return the sum of values in the Brillouin zone
aslist: all output returned as a Python list

Notes

All invocations of sub-methods are added these keyword-only arguments:

etabool, optional: if true a progress-bar is created, default false.
wrapcallable, optional: a function that accepts the output of the given routine and post-process it. Defaults to lambda x: x.

Examples

>>> obj = BrillouinZone(...)
>>> obj.asnone().eigh(eta=True)

assum(self)¶

Return self with summed quantities

This forces the __call__ routine to return all k-point values summed.

See also

asarray: all output as a single array
asyield: all output returned through an iterator
asaverage: take the average (with k-weights) of the Brillouin zone
aslist: all output returned as a Python list

Notes

All invocations of sub-methods are added these keyword-only arguments:

etabool, optional: if true a progress-bar is created, default false.
wrapcallable, optional: a function that accepts the output of the given routine and post-process it. Defaults to lambda x: x.

Examples

>>> obj = BrillouinZone(Hamiltonian)
>>> obj.assum().DOS(np.linspace(-2, 2, 100))

>>> obj = BrillouinZone(Hamiltonian)
>>> obj.assum()
>>> obj.DOS(np.linspace(-2, 2, 100))
>>> obj.PDOS(np.linspace(-2, 2, 100), eta=True)

>>> E = np.linspace(-2, 2, 100)
>>> dist = get_distribution('gaussian', smearing=0.1)
>>> def wrap(es, parent, k, weight):
...    DOS = es.DOS(E, distribution=dist) * weight
...    PDOS = es.PDOS(E, distribution=dist) * weight
...    occ = es.occupation()
...    spin_moment = (es.spin_moment(E, distribution=dist) * occ.reshape(-1, 1)).sum(0) * weight
...    return oplist([DOS, PDOS, spin_moment])
>>> bz = BrillouinZone(hamiltonian)
>>> DOS, PDOS, spin_moment = bz.assum().eigenstate(wrap=wrap)

asyield(self)¶

Return self with yielded quantities

This forces the __call__ routine to return a an iterator which may yield the quantities calculated.

See also

asarray: all output as a single array
asaverage: take the average (with k-weights) of the Brillouin zone
assum: return the sum of values in the Brillouin zone
aslist: all output returned as a Python list

Notes

All invocations of sub-methods are added these keyword-only arguments:

etabool, optional: if true a progress-bar is created, default false.
wrapcallable, optional: a function that accepts the output of the given routine and post-process it. Defaults to lambda x: x.

Examples

>>> obj = BrillouinZone(Hamiltonian)
>>> obj.asyield().eigh(eta=True)

call(self, func, *args, **kwargs)¶

Call the function func and run as though the function has been called

This is a wrapper to call user-defined functions not attached to the parent object.

The below example shows that the equivalence of the call.

Parameters

funccallable: method used
*args :: arguments passed to func in the call sequence
**kwargs :: keyword arguments passed to func in the call sequence

Examples

>>> H = Hamiltonian(...)
>>> bz = BrillouinZone(H)
>>> bz.eigh() == bz.call(H.eigh)

property cell¶

copy(self)¶: Create a copy of this object

static in_primitive(k)¶

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

Parameters

karray_like: k-point(s) to move into the primitive cell

Returns

kall k-points moved into the primitive cell

iter(self, ret_weight=False)¶

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

Parameters

ret_weightbool, optional: if true, also yield the weight for the respective k-point

Yields

kptk-point
weightweight of k-point, only if ret_weight is true.

property k¶: A list of all k-points (if available)

lineark(self, ticks=False)[source]¶

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

This is meant for plotting

Parameters

ticksbool, optional

if True the ticks for the points are also returned

lk, xticks, label_ticks, lk = BandStructure.lineark(True)

Returns

linear_kThe positions in reciprocal space determined by the distance between points
k_tickLinear k-positions of the points, only returned if ticks is True
k_labelLabels at k_tick, only returned if ticks is True

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])

lineartick(self)[source]¶

The tick-marks corresponding to the linear-k values

Returns

linear_kThe positions in reciprocal space determined by the distance between points

See also

lineark: Routine used to calculate the tick-marks.

classmethod param_circle(sc, N_or_dk, kR, normal, origo, loop=False)¶

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

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

scSuperCell, or SuperCellChild: the supercell used to construct the k-points
N_or_dkint: 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.
kRfloat: radius of the k-point. In 1/Ang
normalarray_like of float: normal vector to determine the circle plane
origoarray_like of float: origo of the circle used to generate the circular parameterization
loopbool, optional: whether the first and last point are equal

Returns

BrillouinZonewith the parameterized k-points.

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[:, :]

classmethod parametrize(sc, func, N, *args, **kwargs)¶

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.

Basically this generates a new BrillouinZone object as:

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

Parameters

scSuperCell, or SuperCellChild: the supercell used to construct the k-points
funccallable: method that parameterizes the k-points, must at least accept two arguments, sc (super-cell object containing the unit-cell and reciprocal cell) and frac (current parametrization fraction, between 0 and (N-1)/N. It must return a k-point in 3 dimensions.
Nint: number of k-points generated using the parameterization
argslist of arguments: arguments passed directly to func
kwargsdictionary of arguments: keyword arguments passed directly to func

property rcell¶

set_parent(self, parent)¶

Update the parent associated to this object

Parameters

parentobject or array_like: an object containing cell vectors

tocartesian(self, k)¶

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

Parameters

klist of float: k-point in reduced coordinates

Returns

kin units of 1/Ang

toreduced(self, k)¶

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

Parameters

klist of float: k-point in Cartesian coordinates

Returns

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

property weight¶: Weight of the k-points in the BrillouinZone object

write(self, sile, *args, **kwargs)¶

Writes k-points to a tableSile.

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