sisl.physics.BrillouinZone
- class sisl.physics.BrillouinZone(parent, k=None, weight=None)
Bases:
object
A class to construct Brillouin zone related quantities
It takes any object (which has access to cell-vectors) as an argument and can then return the k-points in non-reduced units from reduced units.
The object associated with the BrillouinZone object has to implement at least two different properties:
The object may also be an array of floats in which case an internal Lattice object will be created from the cell vectors (see Lattice for details).
- Parameters:
parent (object or array_like) – An object with associated
parent.cell
andparent.rcell
or an array of floats which may be turned into a Latticek (array_like, optional) – k-points that this Brillouin zone represents
weight (scalar or array_like, optional) – weights for the k-points.
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]
iter
([ret_weight])An iterator for the k-points and (possibly) the weights
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 separationsset_parent
(parent)Update the parent associated to this object
tocartesian
(k)Transfer a k-point in reduced coordinates to the Cartesian coordinates
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
.Loop over all k-points by applying parent methods for all k.
A list of all k-points (if available)
Handles all plotting possibilities for a class
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) BrillouinZone
Create a copy of this object, optionally changing the parent
- Parameters:
parent (optional) – change the parent
bz (BrillouinZone)
- Return type:
- static in_primitive(k)[source]
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:
- iter(ret_weight: bool = False)[source]
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.)
- static merge(bzs, weight_scale: Sequence[float] | float = 1.0, parent=None)[source]
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
andbzs[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:
- classmethod param_circle(parent, N_or_dk: int | float, kR: float, normal, origin, loop=False)[source]
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, optional) – 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:
- Parameters:
- static parametrize(parent, func, N: Sequence[int] | int, *args, **kwargs)[source]
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 (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
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)[source]
Update the parent associated to this object
- Parameters:
parent (object or array_like) – an object containing cell vectors
- volume(ret_dim: bool = False, axes: CellAxes | None = None)[source]
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
- 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:
bz (BrillouinZone)
sile (sisl.typing.SileLike)
- Return type:
None