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 SuperCell object will be created from the cell vectors (see SuperCell 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 SuperCellk (array_like, optional) – k-points that this Brillouin zone represents
weight (array_like, optional) – weights for the k-points. Must have the same length as
k
.
Methods
asarray
()Return self with
numpy.ndarray
returned quantitiesReturn self with k-averaged quantities
Return self with
xarray.DataArray
returned quantitiesaslist
()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
([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
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 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
write
(sile, *args, **kwargs)Writes k-points to a
tableSile
.A dispatcher for classes, using __get__ it converts into ObjectDispatcher upon invocation from an object, or a TypeDispatcher when invoked from a class
A list of all k-points (if available)
Weight of the k-points in the
BrillouinZone
object- __call__(*args, **kwargs)[source]¶
Calls the given attribute of the internal object and returns the quantity
- Parameters
*args (optional) – arguments passed to the attribute call, note that an argument k=k will be added by this routine as a way to loop the k-points.
**kwargs (optional) – keyword arguments passed to the attribute call, note that the first argument will always be
k
- Returns
whatever
getattr(self, attr)(k, *args, **kwargs)
returns- Return type
*
- apply¶
A dispatcher for classes, using __get__ it converts into ObjectDispatcher upon invocation from an object, or a TypeDispatcher when invoked from a class
This is a class-placeholder allowing a dispatecher to be a class attribute and converted into an ObjectDispatcher when invoked from an object.
If it is called on the class, it will return a TypeDispatcher.
This class should be an attribute of a class. It heavily relies on the __get__ special method.
- Parameters
name (str) – name of the attribute in the class
dispatchs (dict, optional) – dictionary of dispatch methods
obj_getattr (callable, optional) – method with 2 arguments, an
obj
and theattr
which may be used to control how the attribute is called.instance_dispatcher (AbstractDispatcher, optional) – control how instance dispatchers are handled through __get__ method. This controls the dispatcher used if called from an instance.
type_dispatcher (AbstractDispatcher, optional) – control how class dispatchers are handled through __get__ method. This controls the dispatcher used if called from a class.
Examples
>>> class A: ... new = ClassDispatcher("new", obj_getattr=lambda obj, attr: getattr(obj.sub, attr))
The above defers any attributes to the contained A.sub attribute.
- asarray()[source]¶
Return self with
numpy.ndarray
returned quantitiesThis 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)
- asaverage()[source]¶
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)
- asdataarray()[source]¶
Return self with
xarray.DataArray
returned quantitiesThis forces the
__call__
routine to return a singlexarray.DataArray
.Notes
Please use
self.apply.dataarray
instead. This method will be deprecated >0.9.9.If you wrap the sub-method to return multiple data-sets, you should use asdataset instead which returns a combination of data-arrays (so-called
xarray.Dataset
).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
.- coordslist of str or list of (str, array), optional
a list of coordinates used in
xarray.DataArray(..., coords=coords)
. By default the coordinates are named['k', 'v1', 'v2', ...]
depending on the shape of the returned quantity. These may optionally be a list of tuples (not a dictionary)!
Examples
>>> obj = BrillouinZone(...) >>> obj.asdataarray().eigh(eta=True)
- aslist()[source]¶
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)
- asnone()[source]¶
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.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)
- assum()[source]¶
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)
- asyield()[source]¶
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)
- call(func, *args, **kwargs)[source]¶
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(parent=None)[source]¶
Create a copy of this object, optionally changing the parent
- Parameters
parent (optional) – change the parent
- 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=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.)
- property k¶
A list of all k-points (if available)
- classmethod param_circle(sc, N_or_dk, kR, normal, origo, loop=False)[source]¶
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
- classmethod parametrize(sc, func, N, *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.
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
- property rcell¶
- set_parent(parent)[source]¶
Update the parent associated to this object
- Parameters
parent (object or array_like) – an object containing cell vectors
- tocartesian(k)[source]¶
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
- toreduced(k)[source]¶
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
- property weight¶
Weight of the k-points in the
BrillouinZone
object