sisl.physics.Bloch

class sisl.physics.Bloch

Bases: object

Bloch’s theorem object containing unfolding factors and unfolding algorithms

This class is a wrapper for expanding any matrix from a smaller matrix cell into a larger, using Bloch’s theorem. The general idea may be summarized in the following equation:

$$\begin{array}{r}{\mathbf{M}}_K^N=\frac{1}{N}\sum _{\begin{array}{c}j=0\\ k_j=\frac{K+j}{N}\end{array}}^{N-1}\left[\begin{array}{ccc}1& \cdots & e^{i(1-N)k_j}\\ e^{i{k}_j}& \cdots & e^{i(2-N)k_j}\\ ⋮& \ddots & ⋮\\ e^{i(N-1)k_j}& \cdots & 1\end{array}\right]\otimes {\mathbf{M}}_{k_j}^1.\end{array}$$

Parameters:

bloch ((3,) int) – Bloch repetitions along each direction

Examples

>>> bloch = Bloch([2, 1, 2])
>>> k_unfold = bloch.unfold_points([0] * 3)
>>> M = [func(*args, k=k) for k in k_unfold]
>>> bloch.unfold(M, k_unfold)

Methods

unfold(M, k_unfold)	Unfold the matrix list of matrices M into a corresponding k-point (unfolding k-points are k_unfold)
unfold_points(k)	Return a list of k-points to be evaluated for this objects unfolding

Attributes

bloch

Number of Bloch expansions along each lattice vector

__call__(func, k, *args, **kwargs)

Return a functions return values as the Bloch unfolded equivalent according to this object

Calling the Bloch object is a shorthand for the manual use of the Bloch.unfold_points and Bloch.unfold methods.

This call structure is a shorthand for:

>>> bloch = Bloch([2, 1, 2])
>>> k_unfold = bloch.unfold_points([0] * 3)
>>> M = [func(*args, k=k) for k in k_unfold]
>>> bloch.unfold(M, k_unfold)

Notes

The function passed must have a keyword argument k.

Parameters:

• func (callable) – method called which returns a matrix.

• k ((3, ) of float) – k-point to be unfolded

• *args (list) – arguments passed directly to func

• **kwargs (dict) – keyword arguments passed directly to func

Returns:

unfolded Bloch matrix

Return type:

numpy.ndarray

unfold(M, k_unfold)

Unfold the matrix list of matrices M into a corresponding k-point (unfolding k-points are k_unfold)

Parameters:

• M ((:, :, :)) – an *-N-M matrix used for unfolding

• k_unfold ((:, 3) of float) – unfolding k-points as returned by Bloch.unfold_points

Returns:

unfolded matrix of size M[0].shape * k_unfold.shape[0] ** 2

Return type:

numpy.ndarray

unfold_points(k)

Return a list of k-points to be evaluated for this objects unfolding

The k-point k is with respect to the unfolded geometry. The return list of k points are the k-points required to be sampled in the folded geometry.

Parameters:

k ((3,) of float) – k-point evaluation corresponding to the unfolded unit-cell

Returns:

a list of np.prod(self.bloch) k-points used for the unfolding

Return type:

numpy.ndarray

property bloch

Number of Bloch expansions along each lattice vector