MonkhorstPack¶

class sisl.physics.MonkhorstPack(parent, nkpt, displacement=None, size=None, centered=True, trs=True)¶

Bases: sisl.physics.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 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

`__dict__`
`__doc__`
`__module__`
`__weakref__`	list of weak references to the object (if defined)
`_bz_attr`
`apply`
`cell`
`k`	A list of all k-points (if available)
`rcell`
`weight`	Weight of the k-points in the `BrillouinZone` object

Methods

`__call__`(args, *kwargs)	Calls the given attribute of the internal object and returns the quantity
`__delattr__`	Implement delattr(self, name).
`__dir__`	Default dir() implementation.
`__eq__`	Return self==value.
`__format__`	Default object formatter.
`__ge__`	Return self>=value.
`__getattr__`(attr)
`__getattribute__`	Return getattr(self, name).
`__getstate__`()	Return dictionary with the current state
`__gt__`	Return self>value.
`__hash__`	Return hash(self).
`__init__`(parent, nkpt[, displacement, size, …])	Initialize self.
`__init_subclass__`	This method is called when a class is subclassed.
`__iter__`([ret_weight])	An iterator for the k-points and (possibly) the weights
`__le__`	Return self<=value.
`__len__`()
`__lt__`	Return self<value.
`__ne__`	Return self!=value.
`__new__`	Create and return a new object.
`__reduce__`	Helper for pickle.
`__reduce_ex__`	Helper for pickle.
`__repr__`	Return repr(self).
`__setattr__`	Implement setattr(self, name, value).
`__setstate__`(state)	Reset state of the object
`__sizeof__`	Size of object in memory, in bytes.
`__str__`()	String representation of MonkhorstPack
`__subclasshook__`	Abstract classes can override this to customize issubclass().
`_bz_get_func`()	Internal method to retrieve the actual function to be called
`asarray`()	Return self with `numpy.ndarray` returned quantities
`asaverage`()	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
`call`(func, args, *kwargs)	Call the function func and run as though the function has been called
`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 separations
`replace`(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`.

apply¶

asarray()¶

Return self with numpy.ndarray returned quantities

This forces the __call__ routine to return a single array.

Notes

Please use self.apply.array instead. This method will be deprecated >0.9.9.

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.asarray().eigenstate(wrap=wrap)

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

asaverage()¶

Return self with k-averaged quantities

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

Notes

Please use self.apply.average instead. This method will be deprecated >0.9.9.

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)

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

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.

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.
data_axisint, 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)

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

aslist()¶

Return self with list returned quantities

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

Notes

Please use self.apply.list instead. This method will be deprecated >0.9.9.

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)

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

asnone()¶

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.

Notes

Please use self.apply.none instead. This method will be deprecated >0.9.9.

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)

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

assum()¶

Return self with summed quantities

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

Notes

Please use self.apply.sum instead. This method will be deprecated >0.9.9.

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)

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

asyield()¶

Return self with yielded quantities

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

Notes

Please use self.apply.iter instead. This method will be deprecated >0.9.9.

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)

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

call(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.

Examples

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

Parameters

func (callable) – method used
*args – arguments passed to func in the call sequence
**kwargs – keyword arguments passed to func in the call sequence

property cell¶

copy()[source]¶: Create a copy of this object

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 (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)¶

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

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

property 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

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

Returns: with the parameterized k-points.
Return type: BrillouinZone

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

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) and frac (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

property 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.

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

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

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: in units of 1/Ang
Return type: numpy.ndarray

toreduced(k)¶

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

property 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.