MonkhorstPack¶
-
class
sisl.physics.brillouinzone.
MonkhorstPack
(parent, nkpt, displacement=None, size=None, centered=True, trs=True)[source]¶ Create a Monkhorst-Pack grid for the Brillouin zone
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
- nktp : array_like of ints
a list of number of k-points along each cell direction
- displacement : float or array_like of float, optional
the displacement of the evenly spaced grid, a single floating number is the displacement for the 3 directions, else they are the individual displacements
- size : float or array_like of float, optional
the size of the Brillouin zone sampled. This reduces the boundaries of the Brillouin zone around the displacement to the fraction specified. I.e. size must be of values \(]0 ; 1]\). Defaults to the entire BZ. Note that this will also reduce the weights such that the weights are normalized to the entire BZ.
- centered : bool, optional
whether the k-points are \(\Gamma\)-centered (for zero displacement)
- trs : bool, optional
whether time-reversal symmetry exists in the Brillouin zone.
Examples
>>> sc = SuperCell(3.) >>> MonkhorstPack(sc, 10) # 10 x 10 x 10 (with TRS) >>> MonkhorstPack(sc, [10, 5, 5]) # 10 x 5 x 5 (with TRS) >>> MonkhorstPack(sc, [10, 5, 5], trs=False) # 10 x 5 x 5 (without TRS)
Attributes
cell
k
A list of all k-points (if available) rcell
weight
Weight of the k-points in the BrillouinZone
objectMethods
__init__
(parent, nkpt[, displacement, size, …])Initialize self. asarray
()Return self with numpy.ndarray
returned quantitiesasaverage
()Return self with k-averaged quantities asgrid
()Return self with Grid quantities aslist
()Return self with list returned quantities asnone
()Return self with None, this may be done for instance when wrapping the function calls. assum
()Return self with summed quantities asyield
()Return self with yielded quantities copy
()Create a copy of this object grid
(n[, displ, size, centered, trs])Create a grid of n points with an offset of displ and sampling size around displ 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 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 separationsreplace
(k, mp)Replace a k-point with a new set of k-points from a Monkhorst-Pack grid set_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 write
(sile, *args, **kwargs)Writes k-points to a tableSile
.-
asarray
()¶ Return self with
numpy.ndarray
returned quantitiesThis forces the
__call__
routine to return a single array.See also
Notes
All invocations of sub-methods are added these keyword-only arguments:
- eta : bool, optional
- if true a progress-bar is created, default false.
- wrap : callable, 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)
-
asaverage
()¶ Return self with k-averaged quantities
This forces the
__call__
routine to return a single k-averaged value.See also
Notes
All invocations of sub-methods are added these keyword-only arguments:
- eta : bool, optional
- if true a progress-bar is created, default false.
- wrap : callable, 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)
-
asgrid
()[source]¶ Return self with Grid quantities
This forces the
__call__
routine to return all k-point values in a regular grid.The calculation of values on a grid requires some careful thought before running the calculation as the returned grid may be somewhat difficult to comprehend.
See also
Notes
All invocations of sub-methods are added these keyword-only arguments:
- eta : bool, optional
- if true a progress-bar is created, default false.
- wrap : callable, optional
- a function that accepts the output of the given routine and post-process
it. Defaults to
lambda x: x
. - data_axis : int, optional
- the Grid axis to put in the data values in. Has to be specified if the subsequent routine calls return more than 1 data-point per k-point.
- grid_unit : {‘b’, ‘Ang’, ‘Bohr’}, optional
- for ‘b’ the returned grid will be a cube, otherwise the grid will be the reciprocal lattice vectors (for any other value) and in the given reciprocal unit (‘Ang’ => 1/Ang)
Examples
>>> obj = MonkhorstPack(Hamiltonian, [10, 1, 10]) >>> grid = obj.asgrid().eigh(data_axis=1)
-
aslist
()¶ Return self with list returned quantities
This forces the
__call__
routine to return a list with returned values.See also
Notes
All invocations of sub-methods are added these keyword-only arguments:
- eta : bool, optional
- if true a progress-bar is created, default false.
- wrap : callable, 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
()¶ Return self with None, this may be done for instance when wrapping the function calls.
This forces the
__call__
routine to returnNone
. This usage is mainly intended when creating custom wrap function calls.See also
Notes
All invocations of sub-methods are added these keyword-only arguments:
- eta : bool, optional
- if true a progress-bar is created, default false.
- wrap : callable, 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
()¶ Return self with summed quantities
This forces the
__call__
routine to return all k-point values summed.See also
Notes
All invocations of sub-methods are added these keyword-only arguments:
- eta : bool, optional
- if true a progress-bar is created, default false.
- wrap : callable, 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)
-
asyield
()¶ Return self with yielded quantities
This forces the
__call__
routine to return a an iterator which may yield the quantities calculated.See also
Notes
All invocations of sub-methods are added these keyword-only arguments:
- eta : bool, optional
- if true a progress-bar is created, default false.
- wrap : callable, 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)
-
cell
¶
-
classmethod
grid
(n, displ=0.0, size=1.0, centered=True, trs=False)[source]¶ Create a grid of n points with an offset of displ and sampling size around displ
The \(k\)-points are \(\Gamma\) centered.
Parameters: - n : int
number of points in the grid. If trs is
True
this may be smaller than n- displ : float, optional
the displacement of the grid
- size : float, optional
the total size of the Brillouin zone to sample
- centered : bool, optional
if the points are centered
- trs : bool, optional
whether time-reversal-symmetry is applied
Returns: - k : np.ndarray
the list of k-points in the Brillouin zone to be sampled
- w : np.ndarray
weights for the k-points
-
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: - k : all k-points moved into the primitive cell
-
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.
-
k
¶ A list of all k-points (if available)
-
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: - sc : SuperCell, or SuperCellChild
the supercell used to construct the k-points
- 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
- origo : array_like of float
origo of the circle used to generate the circular parameterization
- loop : bool, optional
whether the first and last point are equal
Returns: - BrillouinZone : with 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 separationsGenerator 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: - sc : SuperCell, or SuperCellChild
the supercell used to construct the k-points
- func : callable
method that parameterizes the k-points, must at least accept two arguments,
sc
(super-cell object containing the unit-cell and reciprocal cell) andfrac
(current parametrization fraction, between 0 and(N-1)/N
. It must return a k-point in 3 dimensions.- N : int
number of k-points generated using the parameterization
- args: list of arguments
arguments passed directly to func
- kwargs: dictionary of arguments
keyword arguments passed directly to func
-
rcell
¶
-
replace
(k, mp)[source]¶ Replace a k-point with a new set of k-points from a Monkhorst-Pack grid
This method tries to replace an area corresponding to mp.size around the k-point
k
such that the k-points are replaced. This enables one to zoom in on specific points in the Brillouin zone for detailed analysis.Parameters: - k : array_like
k-point in this object to replace
- mp : MonkhorstPack
object containing the replacement k-points.
Raises: - SislError : if the size of the replacement
MonkhorstPack
grid is not compatible with the k-point spacing in this object.
Examples
This example creates a zoomed-in view of the \(\Gamma\)-point by replacing it with a 3x3x3 Monkhorst-Pack grid.
>>> sc = SuperCell(1.) >>> mp = MonkhorstPack(sc, [3, 3, 3]) >>> mp.replace([0, 0, 0], MonkhorstPack(sc, [3, 3, 3], size=1./3))
This example creates a zoomed-in view of the \(\Gamma\)-point by replacing it with a 4x4x4 Monkhorst-Pack grid.
>>> sc = SuperCell(1.) >>> mp = MonkhorstPack(sc, [3, 3, 3]) >>> mp.replace([0, 0, 0], MonkhorstPack(sc, [4, 4, 4], size=1./3))
This example creates a zoomed-in view of the \(\Gamma\)-point by replacing it with a 4x4x1 Monkhorst-Pack grid.
>>> sc = SuperCell(1.) >>> mp = MonkhorstPack(sc, [3, 3, 3]) >>> mp.replace([0, 0, 0], MonkhorstPack(sc, [4, 4, 1], size=1./3))
-
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: - k : list of float
k-point in reduced coordinates
Returns: - k : in units of 1/Ang
-
toreduced
(k)¶ Transfer a k-point in Cartesian coordinates to the reduced coordinates
Parameters: - k : list of float
k-point in Cartesian coordinates
Returns: - k : in units of reciprocal lattice vectors ]-0.5 ; 0.5] (if k is in the primitive cell)
-
weight
¶ Weight of the k-points in the
BrillouinZone
object
-
write
(sile, *args, **kwargs)¶ Writes k-points to a
tableSile
.This allows one to pass a tableSile or a file-name.