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:

  1. cell which is the lattice vector

  2. rcell which is the reciprocal lattice vectors.

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 and parent.rcell or an array of floats which may be turned into a Lattice

  • k (array-like, optional) – k-points that this Brillouin zone represents

  • weight (scalar or array-like, optional) – weights for the k-points.

Plotting

plot

Plotting functions for the BrillouinZone class.

plot.bands([H, extra_vars, ...])

Creates a BandsData object and then plots a BandsPlot from it.

plot.fatbands([H, extra_vars, ...])

Creates a BandsData object and then plots a FatbandsPlot from it.

plot.sites([axes, sites, ...])

Builds a SitesPlot by setting the value of "sites_obj" to the current object.

\(k\)-point calculations

apply

Loop over all k-points by applying parent methods for all k.

apply.array(method[, eta_key])

Dispatch the method by one array

apply.average(method)

Dispatch the method by averaging

apply.dataarray(method)

Dispatch the method by returning a DataArray or data-set

apply.grid(method[, eta_key])

Dispatch the method by putting values on the grid

apply.iter(method[, eta_key])

Dispatch the method by iterating values

apply.list(method)

Dispatch the method by returning list of values

apply.ndarray(method[, eta_key])

Dispatch the method by one array

apply.none(method)

Dispatch the method by doing nothing (mostly useful if wrapped)

apply.oplist(method)

Dispatch the method by returning oplist of values

apply.sum(method)

Dispatch the method by summing

apply.xarray(method)

Dispatch the method by returning a DataArray or data-set

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 separations

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.

Attributes

cell

k

A list of all k-points (if available)

rcell

weight

Weight of the k-points in the BrillouinZone object

apply.array(method, eta_key='ndarray')

Dispatch the method by one array

apply.average(method)

Dispatch the method by averaging

apply.dataarray(method)

Dispatch the method by returning a DataArray or data-set

apply.grid(method, eta_key='grid')

Dispatch the method by putting values on the grid

apply.iter(method, eta_key='iter')

Dispatch the method by iterating values

apply.list(method)

Dispatch the method by returning list of values

apply.ndarray(method, eta_key='ndarray')

Dispatch the method by one array

apply.none(method)

Dispatch the method by doing nothing (mostly useful if wrapped)

apply.oplist(method)

Dispatch the method by returning oplist of values

apply.sum(method)

Dispatch the method by summing

apply.xarray(method)

Dispatch the method by returning a DataArray or data-set

copy(parent=None) BrillouinZone

Create a copy of this object, optionally changing the parent

Parameters:

parent (optional) – change the parent

static in_primitive(k: numpy.typing.ArrayLike) ndarray[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:

numpy.ndarray – all k-points moved into the primitive cell

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

BrillouinZone – even if all objects are not BrillouinZone objects the returned object will be.

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

BrillouinZone – with the parameterized k-points.

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

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

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.bands(H: Hamiltonian | None = None, extra_vars: Sequence[dict | str] = (), *, Erange: tuple[float, float] | None = None, E0: float = 0.0, E_axis: Literal['x', 'y'] = 'y', bands_range: tuple[int, int] | None = None, spin: Literal[0, 1] | None = None, bands_style: StyleSpec = {'color': 'black', 'dash': 'solid', 'opacity': 1, 'width': 1}, spindown_style: StyleSpec = {'color': 'blue', 'width': 1}, colorscale: Colorscale | None = None, gap: bool = False, gap_tol: float = 0.01, gap_color: str = 'red', gap_marker: dict = {'size': 7}, direct_gaps_only: bool = False, custom_gaps: Sequence[dict] = [], line_mode: Literal['line', 'scatter', 'area_line'] = 'line', group_legend: bool = True, backend: str = 'plotly') BandsPlot

Creates a BandsData object and then plots a BandsPlot from it.

Parameters:
  • H – The Hamiltonian to use for the calculations. If None, the parent of the Brillouin zone will be used, which is typically what you want!

  • extra_vars – Additional variables to calculate for each eigenstate, apart from their energy. Each item of the list should be a dictionary with the following keys:

    • ‘name’, str: The name of the variable.

    • ‘getter’, callable: A function that gets 3 arguments: eigenstate, plot and

    spin index, and returns the values of the variable in a numpy array. This function will be called for each eigenstate object separately. That is, once for each (k-point, spin) combination. - ‘coords’, tuple of str: The names of the dimensions of the returned array. The number of coordinates should match the number of dimensions. - ‘coords_values’, dict: If this variable introduces a new coordinate, you should pass the values for that coordinate here. If the coordinates were already defined by another variable, they will already have values. If you are unsure that the coordinates are new, just pass the values for them, they will get overwritten.

    Each item can also be a string indicating the name of a known variable: ‘norm2’, ‘spin_moment’, ‘ipr’.

  • Erange – The energy range to plot. If None, the range is determined by bands_range.

  • E0 – The energy reference.

  • E_axis – Axis to plot the energies.

  • bands_range – The bands to plot. Only used if Erange is None. If None, the 15 bands above and below the Fermi level are plotted.

  • spin – Which spin channel to display. Only meaningful for spin-polarized calculations. If None and the calculation is spin polarized, both are plotted.

  • bands_style – Styling attributes for bands.

  • spindown_style – Styling attributes for the spin down bands (if present). Any missing attribute will be taken from bands_style.

  • colorscale – Colorscale to use for the bands in case the color attribute is an array of values. If None, the default colorscale is used for each backend.

  • gap – Whether to display the gap.

  • gap_tol – Tolerance in k for determining whether two gaps are the same.

  • gap_color – Color of the gap.

  • gap_marker – Marker styles for the gap (as plotly marker’s styles).

  • direct_gaps_only – Whether to only display direct gaps.

  • custom_gaps – List of custom gaps to display. See the showcase notebooks for examples.

  • line_mode – The method used to draw the band lines.

  • group_legend – Whether to group all bands in the legend to show a single legend item.

    If the bands are spin polarized, bands are grouped by spin channel.

  • backend – The backend to use to generate the figure.

See also

BandsPlot

The plot class used to generate the plot.

BandsData

The class to which data is converted.

plot.fatbands(H: Hamiltonian | None = None, extra_vars: Sequence[dict | str] = (), *, Erange: tuple[float, float] | None = None, E0: float = 0.0, E_axis: Literal['x', 'y'] = 'y', bands_range: tuple[int, int] | None = None, spin: Literal[0, 1] | None = None, bands_style: StyleSpec = {'color': 'black', 'opacity': 1, 'width': 1}, spindown_style: StyleSpec = {'color': 'blue', 'width': 1}, gap: bool = False, gap_tol: float = 0.01, gap_color: str = 'red', gap_marker: dict = {'size': 7}, direct_gaps_only: bool = False, custom_gaps: Sequence[dict] = [], bands_mode: Literal['line', 'scatter', 'area_line'] = 'line', bands_group_legend: bool = True, groups: OrbitalQueries = [], fatbands_var: str = 'norm2', fatbands_mode: Literal['line', 'scatter', 'area_line'] = 'area_line', fatbands_scale: float = 1.0, backend: str = 'plotly') FatbandsPlot

Creates a BandsData object and then plots a FatbandsPlot from it.

Parameters:
  • H – The Hamiltonian to use for the calculations. If None, the parent of the Brillouin zone will be used, which is typically what you want!

  • extra_vars – Additional variables to calculate for each eigenstate, apart from their energy. Each item of the list should be a dictionary with the following keys:

    • ‘name’, str: The name of the variable.

    • ‘getter’, callable: A function that gets 3 arguments: eigenstate, plot and

    spin index, and returns the values of the variable in a numpy array. This function will be called for each eigenstate object separately. That is, once for each (k-point, spin) combination. - ‘coords’, tuple of str: The names of the dimensions of the returned array. The number of coordinates should match the number of dimensions. - ‘coords_values’, dict: If this variable introduces a new coordinate, you should pass the values for that coordinate here. If the coordinates were already defined by another variable, they will already have values. If you are unsure that the coordinates are new, just pass the values for them, they will get overwritten.

    Each item can also be a string indicating the name of a known variable: ‘norm2’, ‘spin_moment’, ‘ipr’.

  • Erange – The energy range to plot. If None, the range is determined by bands_range.

  • E0 – The energy reference.

  • E_axis – Axis to plot the energies.

  • bands_range – The bands to plot. Only used if Erange is None. If None, the 15 bands above and below the Fermi level are plotted.

  • spin – Which spin channel to display. Only meaningful for spin-polarized calculations. If None and the calculation is spin polarized, both are plotted.

  • bands_style – Styling attributes for bands.

  • spindown_style – Styling attributes for the spin down bands (if present). Any missing attribute will be taken from bands_style.

  • gap – Whether to display the gap.

  • gap_tol – Tolerance in k for determining whether two gaps are the same.

  • gap_color – Color of the gap.

  • gap_marker – Marker styles for the gap (as plotly marker’s styles).

  • direct_gaps_only – Whether to only display direct gaps.

  • custom_gaps – List of custom gaps to display. See the showcase notebooks for examples.

  • bands_mode – The method used to draw the band lines.

  • bands_group_legend – Whether to group all bands in the legend to show a single legend item.

    If the bands are spin polarized, bands are grouped by spin channel.

  • groups – Orbital groups to plots. See showcase notebook for examples.

  • fatbands_var – The variable to use from bands_data to determine the width of the fatbands. This variable must have as coordinates (k, band, orb, [spin]).

  • fatbands_mode – The method used to draw the fatbands.

  • fatbands_scale – Factor that scales the size of all fatbands.

  • backend – The backend to use to generate the figure.

See also

FatbandsPlot

The plot class used to generate the plot.

BandsData

The class to which data is converted.

plot.sites(axes: Axes = ['x', 'y', 'z'], sites: AtomsIndex = None, sites_style: Sequence[AtomsStyleSpec] = [], sites_scale: float = 1.0, sites_name: str = 'Sites', sites_colorscale: Colorscale | None = None, drawing_mode: Literal['scatter', 'balls', 'line', None] = None, show_cell: Literal['box', 'axes', False] = False, cell_style: StyleSpec = {}, nsc: tuple[int, int, int] = (1, 1, 1), sites_ndim_scale: tuple[float, float, float] = (1, 1, 1), dataaxis_1d: np.ndarray | Callable | None = None, arrows: Sequence[AtomArrowSpec] = (), backend='plotly') SitesPlot

Builds a SitesPlot by setting the value of “sites_obj” to the current object.

Plots sites from an object that can be parsed into a geometry.

The only differences between this plot and a geometry plot is the naming of the inputs and the fact that there are no options to plot bonds.

Parameters:
  • axes – The axes to project the sites to.

  • sites – The sites to plot. If None, all sites are plotted.

  • sites_style – List of style specifications for the sites. See the showcase notebooks for examples.

  • sites_scale – Scaling factor for the size of all sites.

  • sites_name – Name to give to the trace that draws the sites.

  • sites_colorscale – Colorscale to use for the sites in case the color attribute is an array of values. If None, the default colorscale is used for each backend.

  • drawing_mode – The method used to draw the sites.

  • show_cell – Mode to display the reciprocal cell. If False, the cell is not displayed.

  • cell_style – Style specification for the reciprocal cell. See the showcase notebooks for examples.

  • nsc – Number of unit cells to display in each direction.

  • sites_ndim_scale – Scaling factor for the size of the sites for different dimensionalities (1D, 2D, 3D).

  • dataaxis_1d – Only meaningful for 1D plots. The data to plot on the Y axis.

  • arrows – List of arrow specifications to display. See the showcase notebooks for examples.

  • backend – The backend to use to generate the figure.

set_parent(parent) None[source]

Update the parent associated to this object

Parameters:

parent (object or array_like) – an object containing cell vectors

tocartesian(k: npt.ArrayLike | None = None) np.ndarray[source]

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

Parameters:

k – k-point in reduced coordinates, defaults to this objects k-points.

Returns:

numpy.ndarray – in units of 1/Ang

toreduced(k: numpy.typing.ArrayLike) ndarray[source]

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

Parameters:

k (list of float) – k-point in Cartesian coordinates

Returns:

numpy.ndarray – in units of reciprocal lattice vectors ]-0.5 ; 0.5] (if k is in the primitive cell)

volume(ret_dim: bool = False, axes: CellAxes | None = None) float | tuple[float, int][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 – also return the dimensionality of the system

  • axes – 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

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.

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

A list of all k-points (if available)

plot

Plotting functions for the BrillouinZone class.

property rcell: ndarray
property weight: ndarray

Weight of the k-points in the BrillouinZone object