Brillouin zone sampling

The k-points are always given relative to the basis vectors of the reciprocal unit cell.

Monkhorst-Pack

ase.dft.kpoints.monkhorst_pack(size)[source]

Construct a uniform sampling of k-space of given size.

The k-points are given as [MonkhorstPack]:

\[\sum_{i=1,2,3} \frac{2n_i -N_i - 1}{2N_i} \mathbf{b}_i,\]

where \(n_i=1,2,...,N_i\), size = \((N_1, N_2, N_3)\) and the \(\mathbf{b}_i\)‘s are reciprocal lattice vectors.

ase.dft.kpoints.get_monkhorst_pack_size_and_offset(kpts)[source]

Find Monkhorst-Pack size and offset.

Returns (size, offset), where:

kpts = monkhorst_pack(size) + offset.

The set of k-points must not have been symmetry reduced.

Example:

>>> from ase.dft.kpoints import *
>>> monkhorst_pack((4, 1, 1))
array([[-0.375,  0.   ,  0.   ],
       [-0.125,  0.   ,  0.   ],
       [ 0.125,  0.   ,  0.   ],
       [ 0.375,  0.   ,  0.   ]])
>>> get_monkhorst_pack_size_and_offset([[0, 0, 0]])
(array([1, 1, 1]), array([ 0.,  0.,  0.]))
[MonkhorstPack]Hendrik J. Monkhorst and James D. Pack: Special points for Brillouin-zone integrations, Phys. Rev. B 13, 5188–5192 (1976)

Special points in the Brillouin zone

ase.dft.kpoints.special_points

Special points from [Setyawana-Curtarolo]:

Cubic GXMGRX,MR ../../_images/cubic.svg
FCC GXWKGLUWLK,UX ../../_images/fcc.svg
BCC GHNGPH,PN ../../_images/bcc.svg
Tetragonal GXMGZRAZ,XR,MA ../../_images/tetragonal.svg
Orthorhombic GXSYGZURTZ,YT,UX,SR ../../_images/orthorhombic.svg
Hexagonal GMKGALHA,LM,KH ../../_images/hexagonal.svg
Monoclinic GYHCEM1AXH1,MDZ,YD ../../_images/monoclinic.svg
[Setyawana-Curtarolo](1, 2)

High-throughput electronic band structure calculations: Challenges and tools

Wahyu Setyawana, Stefano Curtarolo

Computational Materials Science, Volume 49, Issue 2, August 2010, Pages 299–312

http://dx.doi.org/10.1016/j.commatsci.2010.05.010

You can find the special points in the Brillouin zone:

>>> from ase.build import bulk
>>> from ase.dft.kpoints import get_special_points
>>> from ase.dft.kpoints import bandpath
>>> si = bulk('Si', 'diamond', a=5.459)
>>> points = get_special_points('fcc', si.cell)
>>> GXW = [points[k] for k in 'GXW']
>>> kpts, x, X = bandpath(GXW, si.cell, 100)
>>> print(kpts.shape, len(x), len(X))
(100, 3) 100 3
ase.dft.kpoints.get_special_points(cell, lattice=None, eps=0.0002)[source]

Return dict of special points.

The definitions are from a paper by Wahyu Setyawana and Stefano Curtarolo:

http://dx.doi.org/10.1016/j.commatsci.2010.05.010
cell: 3x3 ndarray
Unit cell.
lattice: str
Optionally check that the cell is one of the following: cubic, fcc, bcc, orthorhombic, tetragonal, hexagonal or monoclinic.
eps: float
Tolerance for cell-check.
ase.dft.kpoints.bandpath(path, cell, npoints=50)[source]

Make a list of kpoints defining the path between the given points.

path: list or str

Can be:

  • a string that parse_path_string() understands: ‘GXL’
  • a list of BZ points: [(0, 0, 0), (0.5, 0, 0)]
  • or several lists of BZ points if the the path is not continuous.
cell: 3x3
Unit cell of the atoms.
npoints: int
Length of the output kpts list.

Return list of k-points, list of x-coordinates and list of x-coordinates of special points.

ase.dft.kpoints.parse_path_string(s)[source]

Parse compact string representation of BZ path.

A path string can have several non-connected sections separated by commas. The return value is a list of sections where each section is a list of labels.

Examples:

>>> parse_path_string('GX')
[['G', 'X']]
>>> parse_path_string('GX,M1A')
[['G', 'X'], ['M1', 'A']]
ase.dft.kpoints.labels_from_kpts(kpts, cell, eps=1e-05)[source]

Get an x-axis to be used when plotting a band structure.

The first of the returned lists can be used as a x-axis when plotting the band structure. The second list can be used as xticks, and the third as xticklabels.

Parameters:

kpts: list
List of scaled k-points.
cell: list
Unit cell of the atomic structure.

Returns:

Three arrays; the first is a list of cumulative distances between k-points, the second is x coordinates of the special points, the third is the special points as strings.

Band structure

class ase.dft.band_structure.BandStructure(cell, kpts, energies=None, reference=0.0)[source]

Create band structure object from energies and k-points.

plot(ax=None, spin=None, emin=-10, emax=5, filename=None, show=None, ylabel=None, colors=None, label=None, spin_labels=['spin up', 'spin down'], loc=None, **plotkwargs)[source]

Plot band-structure.

spin: int or None
Spin channel. Default behaviour is to plot both spin up and down for spin-polarized calculations.
emin,emax: float
Maximum energy above reference.
filename: str
Write image to a file.
ax: Axes
MatPlotLib Axes object. Will be created if not supplied.
show: bool
Show the image.
plot_with_colors(ax=None, emin=-10, emax=5, filename=None, show=None, energies=None, colors=None, ylabel=None, clabel='$s_z$', cmin=-1.0, cmax=1.0, sortcolors=False, loc=None, s=2)[source]

Plot band-structure with colors.

static read(filename)[source]

Read from json file.

write(filename)[source]

Write to json file.

Free electron example:

# creates: cu.png
from ase.build import bulk
from ase.calculators.test import FreeElectrons

a = bulk('Cu')
a.calc = FreeElectrons(nvalence=1,
                       kpts={'path': 'GXWLGK', 'npoints': 200})
a.get_potential_energy()
bs = a.calc.band_structure()
bs.plot(emax=10, filename='cu.png')
../../_images/cu.png

Interpolation

ase.dft.kpoints.monkhorst_pack_interpolate(path, values, icell, bz2ibz, size, offset=(0, 0, 0))[source]

Interpolate values from Monkhorst-Pack sampling.

path: (nk, 3) array-like
Desired path in units of reciprocal lattice vectors.
values: (nibz, …) array-like
Values on Monkhorst-Pack grid.
icell: (3, 3) array-like
Reciprocal lattice vectors.
bz2ibz: (nbz,) array-like of int
Map from nbz points in BZ to nibz reduced points in IBZ.
size: (3,) array-like of int
Size of Monkhorst-Pack grid.
offset: (3,) array-like
Offset of Monkhorst-Pack grid.

Returns values interpolated to path.

High symmetry paths

ase.dft.kpoints.special_paths

The special_paths dictionary contains suggestions for high symmetry paths in the BZ from the [Setyawana-Curtarolo] paper.

>>> from ase.dft.kpoints(import special_paths, special_points,
...                      parse_path_string)
>>> paths = special_paths['bcc']
>>> paths
[['G', 'H', 'N', 'G', 'P', 'H'], ['P', 'N']]
>>> points = special_points['bcc']
>>> points
{'H': [0.5, -0.5, 0.5], 'N': [0, 0, 0.5], 'P': [0.25, 0.25, 0.25],
 'G': [0, 0, 0]}
>>> kpts = [points[k] for k in paths[0]]  # G-H-N-G-P-H
>>> kpts
[[0, 0, 0], [0.5, -0.5, 0.5], [0, 0, 0.5], [0, 0, 0], [0.25, 0.25, 0.25], [0.5, -0.5, 0.5]]

Chadi-Cohen

Predefined sets of k-points:

ase.dft.kpoints.cc6_1x1
ase.dft.kpoints.cc12_2x3
ase.dft.kpoints.cc18_sq3xsq3
ase.dft.kpoints.cc18_1x1
ase.dft.kpoints.cc54_sq3xsq3
ase.dft.kpoints.cc54_1x1
ase.dft.kpoints.cc162_sq3xsq3
ase.dft.kpoints.cc162_1x1

Naming convention: cc18_sq3xsq3 is 18 k-points for a sq(3)xsq(3) cell.

Try this:

>>> import numpy as np
>>> import matplotlib.pyplot as plt
>>> from ase.dft.kpoints import cc162_1x1
>>> B = [(1, 0, 0), (-0.5, 3**0.5 / 2, 0), (0, 0, 1)]
>>> k = np.dot(cc162_1x1, B)
>>> plt.plot(k[:, 0], k[:, 1], 'o')  
[<matplotlib.lines.Line2D object at 0x9b61dcc>]
>>> plt.show()
../../_images/cc.png