sisl.physics.MonkhorstPack

class sisl.physics.MonkhorstPack(parent, nkpt: Sequence[int] | int, displacement=None, size=None, centered: bool = True, trs: bool = True)

Bases: BrillouinZone

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 Lattice
nkpt (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

>>> lattice = Lattice(3.)
>>> MonkhorstPack(lattice, 10) # 10 x 10 x 10 (with TRS)
>>> MonkhorstPack(lattice, [10, 5, 5]) # 10 x 5 x 5 (with TRS)
>>> MonkhorstPack(lattice, [10, 5, 5], trs=False) # 10 x 5 x 5 (without TRS)

Methods

`copy`([parent])	Create a copy of this object, optionally changing the parent
`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
`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 separations
`replace`(k, mp[, displacement, as_index, ...])	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
`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`.
`apply`	Loop over all k-points by applying parent methods for all k.
`cell`
`displacement`	Displacement for this Monkhorst-Pack grid
`k`	A list of all k-points (if available)
`plot`	Handles all plotting possibilities for a class
`rcell`
`weight`	Weight of the k-points in the `BrillouinZone` object

__init__(parent, nkpt: Sequence[int] | int, displacement=None, size=None, centered: bool = True, trs: bool = True)[source]

Parameters:

nkpt (Sequence[int] | int)
centered (bool)
trs (bool)

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 passing k 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 wise
apply.datarray if xarray is available one can retrieve an xarray.DataArray instance

Please see Brillouin zone for further examples.

property cell: ndarray

copy(parent=None) → MonkhorstPack

Create a copy of this object, optionally changing the parent

Parameters:

parent (optional) – change the parent
mp (MonkhorstPack)

Return type:

MonkhorstPack

property displacement: Displacement for this Monkhorst-Pack grid

classmethod grid(n, displ: float = 0.0, size: float = 1.0, centered: bool = True, trs: bool = 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 (numpy.ndarray) – the list of k-points in the Brillouin zone to be sampled
w (numpy.ndarray) – weights for the k-points

static in_primitive(k: numpy.typing.ArrayLike) → ndarray

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:: ndarray

iter(ret_weight: bool = 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: ndarray: A list of all k-points (if available)

static merge(bzs, weight_scale: Sequence[float] | float = 1.0, parent=None)

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 and bzs[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:

BrillouinZone

classmethod param_circle(parent, N_or_dk: int | float, kR: float, normal, origin, loop: bool = 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 (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) – 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:

BrillouinZone

Parameters:

N_or_dk (int | float)
kR (float)
loop (bool)

static parametrize(parent, func, N: Sequence[int] | int, *args, **kwargs) → BrillouinZone

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.

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 and i in func will be lists accordingly.
*args – additional arguments passed directly to func
**kwargs – additional keyword arguments passed directly to func

Return type:

BrillouinZone

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: ndarray

replace(k, mp: MonkhorstPack, displacement=False, as_index: bool = False, check_vol: bool = True)[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, if as_index is true, it will be regarded as integer positions of the k-points to replace, otherwise the indices of the k-points will be located individually (in chunks of 200 MB).
mp (MonkhorstPack) – object containing the replacement k-points.
displacement (array_like or bool, optional) – the displacment of the mp k-points. Needed for doing lots of replacements due to efficiency. Defaults to not displace anything. The inserted k-points will be mp.k + displacement. If True, it will use k as the displacement vector. For multiple k-point replacements each k-point will be replaced my mp with k as the displacement.
as_index (bool, optional) – whether k is input as reciprocal k-points, or as indices of k-points in this object.
check_vol (bool, optional) – whether to check the volume of the replaced k-point(s); by default the volume of each k-point is determined by the original size and nkpt values. However, when doing replacements of k-points these values are not kept for the individual k-points that were replaced, so subsequent replacements of these points will cause errors that effectively are not valid.

Examples

This example creates a zoomed-in view of the \(\Gamma\)-point by replacing it with a 3x3x3 Monkhorst-Pack grid.

>>> lattice = Lattice(1.)
>>> mp = MonkhorstPack(lattice, [3, 3, 3])
>>> mp.replace([0, 0, 0], MonkhorstPack(lattice, [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.

>>> lattice = Lattice(1.)
>>> mp = MonkhorstPack(lattice, [3, 3, 3])
>>> mp.replace([0, 0, 0], MonkhorstPack(lattice, [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.

>>> lattice = Lattice(1.)
>>> mp = MonkhorstPack(lattice, [3, 3, 3])
>>> mp.replace([0, 0, 0], MonkhorstPack(lattice, [4, 4, 1], size=1./3))

Raises:

SislError – if the size of the replacement MonkhorstPack grid is not compatible with the k-point spacing in this object.

Parameters:

mp (MonkhorstPack)
as_index (bool)
check_vol (bool)

set_parent(parent) → None

Update the parent associated to this object

Parameters:: parent (object or array_like) – an object containing cell vectors
Return type:: None

tocartesian(k: npt.ArrayLike | None = None) → np.ndarray

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

Parameters:: k (Optional[npt.ArrayLike]) – k-point in reduced coordinates, defaults to this objects k-points.
Returns:: in units of 1/Ang
Return type:: ndarray

toreduced(k: numpy.typing.ArrayLike) → ndarray

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

Parameters:: k (list of float) – k-point in Cartesian coordinates
Returns:: in units of reciprocal lattice vectors ]-0.5 ; 0.5] (if k is in the primitive cell)
Return type:: ndarray

volume(ret_dim: bool = False, axes: CellAxes | None = None) → float | tuple[float, int]

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

Return type:

Union[float, tuple[float, int]]

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